Merge pull request 'build(deps): align with Gitea registry (parent 2.2.1, QQQ 4.1.0-RC.26)' (#42) from deps/align-gitea into develop

Replace the CrmHealthChecks STAND-IN (qqq#1199) adapter onto the
qqq-middleware-health HealthIndicator with checks registered in the QQQ
4.1 core HealthChecksMetaData registry (crm.email, crm.sequence_lag,
crm.lead_score). The core HealthRunner schedules them and runs each as
the core system user. Drop the optional qqq-middleware-health dependency.

Also keep the lead-score incremental watermark at millisecond precision
to match modifyDate, fixing PlatformReuseTest skipping a same-millisecond
change on a warm JVM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.circleci/config.yml

@@ -1,60 +1,14 @@
 version: 2.1
-
+setup: true
 orbs:
-   qqq-orb: kingsrook/qqq-orb@0.6.9
-
-commands:
-   configure-package-install:
-      steps:
-         - run:
-              name: Keep package installation unattended
-              command: |
-                 # These build machines are discarded after the job.
-                 sudo install -d /etc/needrestart/conf.d
-                 printf '%s\n' '$nrconf{restart} = "l";' | sudo tee /etc/needrestart/conf.d/99-qqq-ci.conf >/dev/null
-
+  qqq-orb: kingsrook/qqq-orb@0.8
 workflows:
-   test_only:
-      jobs:
-         - qqq-orb/mvn_test_only:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              filters:
-                 branches:
-                    ignore: /(develop|release\/.*)/
-
-   publish_snapshot:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: snapshot
-              filters:
-                 branches:
-                    only: [develop]
-
-   publish_release_candidate:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release_candidate
-              filters:
-                 branches:
-                    only: [/release\/.*/]
-
-   publish_release:
-      jobs:
-         - qqq-orb/mvn_publish:
-              pre-steps:
-                 - configure-package-install
-              context: [qqq-maven-registry-credentials]
-              branch_type: release
-              filters:
-                 branches:
-                    ignore: /.*/
-                 tags:
-                    only: [/^v\d+\.\d+\.\d+$/]
+  setup:
+    jobs:
+    - qqq-orb/generate_pipeline:
+        orb_version: '0.8'
+        filters:
+          branches:
+            ignore: automation/qbit-rc-pending
+          tags:
+            only: /^v\d+\.\d+\.\d+$/

.gitea/workflows/build.yaml

@@ -0,0 +1,7 @@
+name: build
+on:
+  push:
+jobs:
+  maven:
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/maven.yaml@v1
+    secrets: inherit

.github/workflows/codeql.yml

@@ -0,0 +1,23 @@
+name: CodeQL
+'on':
+  push:
+    branches:
+    - main
+    - develop
+    - release/**
+    - hotfix/**
+  pull_request: {}
+  schedule:
+  - cron: 41 16 * * 0
+  workflow_dispatch: {}
+permissions:
+  contents: read
+  actions: read
+  security-events: write
+  packages: read
+concurrency:
+  group: codeql-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  analyze:
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-codeql.yml@c288a8864fe9054f68410e1d78f5863aea4c4d22

.github/workflows/release-rc.yml

@@ -1,25 +1,74 @@
-# Cut the next release candidate (QRun-IO/qqq docs/QRUN-QBIT-REPO-STANDARD.md, C6):
-# run this workflow by hand, or merge a develop PR labelled `release:rc`. It merges develop into
-# the release line and the release/* push runs CircleCI publish_release_candidate.
 name: Release candidate
-
-on:
+'on':
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Print the plan without merging or creating branches
+        description: Plan a cut without changing release state
         type: boolean
         default: false
+      finalize:
+        description: Retry finalization of an existing cut; do not cut another RC
+        type: boolean
+        default: false
+      recover:
+        description: Recover the same published RC after a deployment timeout; never
+          reupload
+        type: boolean
+        default: false
+      circle_build:
+        description: Original Circle publisher build number (recovery only)
+        type: string
+        default: ''
+      merge_sha:
+        description: Existing cut merge_sha (finalize retry only)
+        type: string
+        default: ''
+      bump_sha:
+        description: Existing cut bump_sha (finalize retry only)
+        type: string
+        default: ''
+      branch:
+        description: Existing cut branch (finalize retry only)
+        type: string
+        default: ''
+      version:
+        description: Existing cut version (finalize retry only)
+        type: string
+        default: ''
   pull_request:
-    types: [closed]
-    branches: [develop]
-
+    types:
+    - closed
+    branches:
+    - develop
+  repository_dispatch:
+    types:
+    - qbit-rc-published
 permissions:
   contents: write
-
+  actions: read
+  checks: read
 jobs:
   release-rc:
-    if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release:rc'))
-    uses: QRun-IO/.github/.github/workflows/qbit-release-rc.yml@main
+    if: github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch'
+      || (github.event_name == 'pull_request' && github.event.pull_request.merged
+      == true && github.event.pull_request.base.ref == 'develop' && contains(github.event.pull_request.labels.*.name,
+      'release:rc'))
+    uses: QRun-IO/qqq-orb/.github/workflows/qbit-release-rc.yml@cc30f599e63c8e41629c99d23395bac1adb8bc44
     with:
-      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+      dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run || false
+        }}
+      finalize: ${{ github.event_name == 'repository_dispatch' || (github.event_name
+        == 'workflow_dispatch' && inputs.finalize) }}
+      recover: ${{ github.event_name == 'workflow_dispatch' && inputs.recover || false
+        }}
+      circle_build: ${{ github.event_name == 'workflow_dispatch' && inputs.circle_build
+        || '' }}
+      merge_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.merge_sha
+        || inputs.merge_sha || '' }}
+      bump_sha: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.bump_sha
+        || inputs.bump_sha || '' }}
+      branch: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.branch
+        || inputs.branch || '' }}
+      version: ${{ github.event_name == 'repository_dispatch' && github.event.client_payload.version
+        || inputs.version || '' }}
+    secrets: inherit

.qqq-ci.yml

@@ -0,0 +1,16 @@
+profile: qbit
+orb_version: '0.8'
+default_branch: develop
+java_version: '21'
+browsers: true
+api_checks: false
+docs_only: false
+release_on_main: false
+release_tag_policy: stable
+test_branch_policy: non-release
+publish:
+  snapshot: true
+  release_candidate: true
+  release: true
+  asciidoc: false
+release_completion: true

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased / 0.2.0
 
+- Register CRM health checks (`crm.email`, `crm.sequence_lag`, `crm.lead_score`) with the QQQ 4.1 core health registry (`HealthChecksMetaData`, qqq#1199), replacing the `qqq-middleware-health` indicator stand-in and its optional dependency.
+
+- Lead scoring keeps its incremental watermark at millisecond precision, matching `modifyDate`, so a contact changed in the same millisecond a pass starts is not skipped.
+
+- Read the CRM QBit metadata version from the Maven-filtered artifact version so release metadata matches the build.
+
+- Adopt QQQ 4.1.0-RC.7 native help bundles, replacing the RC.6 stand-in loader with host-neutral CRM help, live references and the core coverage gate.
+
 - Upgrade to Java 21, QQQ 4.1.0-RC.6 and qbit-build-parent 2.1.2.
 - Add Maven wrapper, CI configuration, architecture guardrails and coverage gates.
 - Rename tables, joins, widgets and CRM processes to `crm_` snake_case, with inferred snake_case SQL columns.
@@ -10,3 +18,8 @@
 - Apply CRM, management and admin permission rules and source-QBit metadata, including an RC.6 widget provenance adapter.
 - Ship PostgreSQL DDL, 33 Liquibase changesets, and H2 persistence and schema tests. 0.2.0 is a fresh install; there is no upgrade path from 0.1.0.
 - Correct installation instructions and document the existing P1 behavior and remaining limitations.
+- Add `crm-defaults.changelog.sql`: insert-only starter data (Sales Pipeline and stages, lifecycle stages, lead sources, industries, win/loss reasons, contact roles, activity types and outcomes, USD base currency). See UPGRADE.md.
+- Add a Setup card to the CRM home (default pipeline, stages, lifecycle stages, base currency, email delivery).
+- Every table help now says how its rows get created; `crm_external_mapping` is documented as not written by the CRM yet.
+- Stamp `crm_currency.rateLastUpdatedDate` when a rate is set or changed; the field is now read-only.
+- Add `CrmTablesGuardrailTest` and a Liquibase-driven defaults test (liquibase-core as a test dependency).

README.md

@@ -57,7 +57,14 @@ qInstance.setEnforcePermissionsInCoreActions(true);
 - `defaultBackendNameForTables`: required backend name.
 - `inferBackendNames`: defaults to true; sets snake_case SQL column names while Java/QQQ field names remain camelCase. SQL table names equal the QQQ table names. Set false only for an explicit host column mapping.
 - `tableMetaDataCustomizer`: optional host table customizer.
-- `securityFields` and `recordSecurityLocks`: retained in P1, applied to contact, company and deal. Host-managed schema columns must match these fields. This is not yet tenant isolation across every child table or workflow.
+- `withTenantSecurityKeyType("tenant")`: enables nullable `tenantKey` fields and record locks. It defaults to null (off). `withTenantAllAccessKeyName("allTenants")` names the host's all-access key. Existing host key types are preserved.
+- Tenant-enabled hosts separately include `src/main/resources/db/liquibase/qbit-crm/crm-tenancy.changelog.sql` **after** the base changelog and explicitly select the `crm-tenancy` context. Single-tenant hosts omit that file. Child records use parent join locks; polymorphic external mappings and internal job checkpoints carry direct tenant keys. Hosts must supply tenant keys on new direct-key records.
+- `withApiName(...)` and `withApiVersion(...)`: publish main and settings tables into an existing host API definition. The host supplies `ApiInstanceMetaData` and includes optional `qqq-middleware-api` at runtime. Main tables declare core search fields.
+- `withEsbDestinationName(...)`: reserved but rejected on RC.6. Its ESB event factory copies all values and has no classified-field exclusion; CRM does not publish those payloads.
+- `CrmBulkLoadProfiles.ensure()`: call once in host startup after registering core's `SavedBulkLoadProfileMetaDataProvider`. It seeds three CSV mappings by label without replacing edited profiles. CRM does not register the core profile tables.
+- Health: the producer registers `crm.email`, `crm.sequence_lag` and `crm.lead_score` with the core health registry (`HealthChecksMetaData`). Hosts that enable core health monitoring (`HealthMetaDataProvider`) get them scheduled by the core `HealthRunner`, which runs each check as the core system user. `CrmHealthChecks.run()` evaluates them once in the caller's context. No check adds permissions or tenant keys or returns personal values.
+
+Help and health both use the core registries (`HelpBundles`, `HealthChecksMetaData`). See [P4B implementation notes](docs/P4B-IMPLEMENTATION.md) for RC.6 limits.
 
 | Scope | Permissions |
 |---|---|
@@ -70,9 +77,19 @@ qInstance.setEnforcePermissionsInCoreActions(true);
 
 Permissions are independent grants. Every CRM-produced table, process and widget has explicit `QPermissionRules` with `DenyBehavior.HIDDEN` and QBit provenance. `security.CrmPermissions.ALL` lists the grants for host administration and tests. The app and widget provenance adapters supply core's `SourceQBitAware` interface because RC.6's app and widget classes lack it.
 
+## Starter defaults
+
+Include `db/liquibase/qbit-crm/crm-defaults.changelog.sql` in the host changelog after `crm.changelog.sql` and, on a tenant-enabled install, after `crm-tenancy.changelog.sql` as well:
+
+```yaml
+- include: { file: db/liquibase/qbit-crm/crm-defaults.changelog.sql }
+```
+
+It seeds, insert-only: the activity types and call/meeting outcomes; the default `Sales Pipeline` (Qualification 10%, Discovery 25%, Proposal 50%, Negotiation 75%, Closed Won 100%, Closed Lost 0%); lifecycle stages (the code looks up `Lead` and `Opportunity` by name); lead sources (`Website` is the web-form default); industries; win and loss reasons (prefixed `Won:` / `Lost:` because names are unique); contact roles; and a USD base currency. Lists are seeded only while empty, so a configured host is unchanged. The lifecycle stages (they change what intake and Convert lead assign) and the base currency are seeded only on a fresh install (no contact, respectively no deal, yet), and the stages only when `Sales Pipeline` is the only pipeline. Rollbacks are empty, so they never delete host rows. Tenant-enabled hosts seed per tenant (the changelog skips tenant-keyed tables). The Setup card on the CRM home shows what is still missing.
+
 ## Tables
 
-All 33 table names and table-backed possible-value sources use `crm_` snake_case. The 23 enum possible-value sources retain their enum names. Relationship columns have indexes; the reference DDL does not impose foreign-key constraints or host-specific tenant columns. Unique constraints match the current QQQ metadata.
+All 34 table names and table-backed possible-value sources use `crm_` snake_case. The 23 enum possible-value sources retain their enum names. Relationship columns have indexes; the reference DDL does not impose foreign-key constraints or host-specific tenant columns. Unique constraints match the current QQQ metadata.
 
 ### Main tables (6)
 
@@ -157,6 +174,24 @@ Later phases complete the following behavior:
 
 The later intake APIs, public subscription routes, collaboration integration, real email transport, durable jobs and the remaining P2 security/integration work are not part of this phase.
 
+## In-app help
+
+CRM registers [help/qbit-crm.yaml](src/main/resources/help/qbit-crm.yaml) from
+`CrmQBitProducer`. The bundle uses the `QBIT` layer and the current artifact version.
+Registration only adds metadata and works without a `helpContent` table; QQQ's
+startup sync skips hosts without that table. Hosts with help storage load help
+and call `HelpBundles.syncOnStartup(qInstance)` after defining their metadata.
+
+To customize wording or describe your deployment, register a separate `HOST`
+bundle with the same entry keys (and roles). HOST text takes precedence over QBIT
+text; the sync preserves user edits for review. Keep live `{{...}}` references
+when referring to labels, defaults or enum values.
+
+`CrmPublicationHelpTest` runs `HelpBundleAssertions` against the produced and
+validated CRM instance, including generated record actions, and also requires
+widget and possible-value help. `CrmTablesGuardrailTest` checks every table's
+row-creation guidance. Run both through `./mvnw -q verify`.
+
 ## Source layout
 
 `CrmQBitProducer` discovers entity, process and widget producers. `core/` holds contacts, companies, forms, lists and consent; `deals/`, `activities/`, `email/` and `scoring/` hold their respective metadata and behavior. `actions/` defines the streamed record actions and their inputs/summaries. `security/` defines permissions, `sync/` holds external mappings and currency utilities, and `widgets/` contains widget producers/renderers. SQL is shipped under `src/main/resources/db/liquibase/qbit-crm/`.

UPGRADE.md

@@ -0,0 +1,24 @@
+# Upgrading
+
+## Starter defaults (Unreleased / 0.2.0)
+
+The CRM now ships `db/liquibase/qbit-crm/crm-defaults.changelog.sql`, a separate insert-only changelog. Without it,
+converting a lead fails with "no default pipeline found", new web leads and converted contacts silently get no
+lifecycle stage, and amounts have no currency prefix.
+
+What a host must do:
+
+1. Add one line to its master changelog, after `crm.changelog.sql` and, on tenant-enabled installs, after `crm-tenancy.changelog.sql` (the file checks for `tenant_key` columns, so the order matters):
+
+   ```yaml
+   - include: { file: db/liquibase/qbit-crm/crm-defaults.changelog.sql }
+   ```
+
+2. Review what it seeds (see README, "Starter defaults"). Existing configuration is never touched: lists are seeded
+   only while their table is empty, the pipeline only when no pipeline exists, its stages only when it is the only pipeline and no stage or deal exists. Lifecycle stages and the base currency are seeded only on a fresh install (no contact, respectively no deal, yet), because they change what intake and Convert lead assign. Rollbacks are empty.
+3. Tenant-enabled hosts (the `crm-tenancy` changelog added `tenant_key` columns): the changelog skips those tables
+   (marks them ran), because rows without a tenant key are invisible to tenants. Insert the same rows once per tenant
+   with `tenant_key` set. The Setup card on the CRM home shows what is still missing.
+4. `crm_currency.rate_last_updated_date` is now written by the CRM when a rate is set or changed and is read-only in
+   the UI. Existing values are kept.
+5. No schema change. `crm_external_mapping` is documented as not written by the CRM yet.

docs/DESIGN.md

@@ -89,8 +89,8 @@ These parts are real and are kept, adapted to 0.2.0:
 | Imports | `importContacts` | core bulk load + saved bulk-load profiles |
 | PII | none | `DataClassification.PII` on every personal field; secured-data tiers apply |
 | Reporting | 14 bespoke widgets | home widgets for the daily view; trend reports via data analysis (`crm_*.analyze`) |
-| Health | none | `crm` health checks (stand-in until core #1199) |
-| Help | none | `help/qbit-crm.yaml` bundle (stand-in loader until core #1198) |
+| Health | none | `crm.*` checks in the core health registry (`HealthChecksMetaData`) |
+| Help | none | `help/qbit-crm.yaml` bundle registered with core `HelpBundles` |
 | Tenancy | clientId lock on 3 tables | configurable tenant key type on every table; the host maps Authentik claims to keys |
 
 ## Data model (33 tables: 6 main, 15 settings, 12 sub-tables)
@@ -268,13 +268,14 @@ signals are logged.
 
 ### Health
 
-`CrmHealthChecks` reports three checks:
-- email transport readiness
-- sequence lag (the oldest due enrollment more than 30 min late)
-- the scoring job's last success time
+`CrmHealthChecks` registers three checks with the core health registry
+(`HealthChecksMetaData`, component `crm`):
+- `crm.email`: email transport readiness
+- `crm.sequence_lag`: the oldest due enrollment more than 30 min late
+- `crm.lead_score`: the scoring job's last success time
 
-It is a `STAND-IN(core=QRun-IO/qqq#1199, removeBy=4.1.0-RC.9)` adapter onto the
-`qqq-middleware-health` `HealthIndicator` until the central `HealthCheck` SPI ships.
+The core `HealthRunner` schedules them on hosts that enable health monitoring and runs each one
+as the core system user. A failing check reports UNKNOWN with a fixed message.
 
 ### Help
 
@@ -282,9 +283,8 @@ It is a `STAND-IN(core=QRun-IO/qqq#1199, removeBy=4.1.0-RC.9)` adapter onto the
 - the app
 - every table, field, action and possible-value source
 
-`HelpBundleAssertions` checks that it is complete. Until `HelpBundles.register` is in a core RC,
-`CrmHelpBundleStandIn` (`STAND-IN(core=QRun-IO/qqq#1198, removeBy=4.1.0-RC.9)`) loads the same
-file into `QHelpContent`.
+The producer registers it with core `HelpBundles.register`; `HelpBundleAssertions` checks that it
+is complete.
 
 ### Contingent dropdowns
 

docs/ddl/postgres.sql

@@ -1,11 +1,12 @@
 -- Copyright 2026 Kingsrook, LLC. Licensed under the Apache License, Version 2.0.
 -- https://www.apache.org/licenses/LICENSE-2.0
--- QBit CRM 0.2.0 P1 PostgreSQL reference schema (33 tables).
+-- QBit CRM 0.2.0 P1 PostgreSQL reference schema (34 tables).
 -- QQQ table names equal SQL names; Java field names map to snake_case columns.
 -- Unique constraints match QQQ metadata. Relationship columns are indexed;
 -- foreign-key constraints are deliberately not imposed (the QQQ/host layer owns
 -- validation and deletion policy, including polymorphic and optional references).
--- Optional host-configured securityFields require matching host-managed columns.
+-- Optional tenancy: separately include crm-tenancy.changelog.sql with context crm-tenancy.
+-- With tenancy off, do not include it; this base schema has no tenant_key columns.
 
 CREATE TABLE IF NOT EXISTS crm_activity (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
@@ -161,27 +162,27 @@ CREATE TABLE IF NOT EXISTS crm_consent_record (
 CREATE INDEX IF NOT EXISTS ix_crm_consent_record_contact_id ON crm_consent_record (contact_id);
 
 CREATE TABLE IF NOT EXISTS crm_contact (
-   first_touch_utm_source VARCHAR(250),
-   first_touch_utm_medium VARCHAR(250),
-   first_touch_utm_campaign VARCHAR(250),
-   first_touch_utm_content VARCHAR(250),
-   first_touch_utm_term VARCHAR(250),
+   first_touch_utm_source VARCHAR(500),
+   first_touch_utm_medium VARCHAR(500),
+   first_touch_utm_campaign VARCHAR(500),
+   first_touch_utm_content VARCHAR(500),
+   first_touch_utm_term VARCHAR(500),
    first_touch_landing_page VARCHAR(1000),
    first_touch_referrer VARCHAR(1000),
    first_touch_date TIMESTAMP WITHOUT TIME ZONE,
-   last_touch_utm_source VARCHAR(250),
-   last_touch_utm_medium VARCHAR(250),
-   last_touch_utm_campaign VARCHAR(250),
-   last_touch_utm_content VARCHAR(250),
-   last_touch_utm_term VARCHAR(250),
+   last_touch_utm_source VARCHAR(500),
+   last_touch_utm_medium VARCHAR(500),
+   last_touch_utm_campaign VARCHAR(500),
+   last_touch_utm_content VARCHAR(500),
+   last_touch_utm_term VARCHAR(500),
    last_touch_landing_page VARCHAR(1000),
    last_touch_referrer VARCHAR(1000),
    last_touch_date TIMESTAMP WITHOUT TIME ZONE,
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
-   first_name VARCHAR(100) NOT NULL,
-   last_name VARCHAR(100) NOT NULL,
-   email VARCHAR(250),
-   secondary_email VARCHAR(250),
+   first_name VARCHAR(100),
+   last_name VARCHAR(100),
+   email VARCHAR(320),
+   secondary_email VARCHAR(320),
    phone VARCHAR(50),
    mobile_phone VARCHAR(50),
    job_title VARCHAR(150),
@@ -189,7 +190,7 @@ CREATE TABLE IF NOT EXISTS crm_contact (
    company_id INTEGER,
    lifecycle_stage_id INTEGER,
    lead_source_id INTEGER,
-   owner_user_id TEXT NOT NULL,
+   owner_user_id TEXT,
    address_line1 VARCHAR(250),
    address_line2 VARCHAR(250),
    city VARCHAR(100),
@@ -252,7 +253,7 @@ CREATE TABLE IF NOT EXISTS crm_deal (
    weighted_amount DECIMAL(20,6),
    company_id INTEGER,
    primary_contact_id INTEGER,
-   owner_user_id TEXT NOT NULL,
+   owner_user_id TEXT,
    lead_source_id INTEGER,
    expected_close_date DATE,
    actual_close_date DATE,
@@ -346,7 +347,7 @@ CREATE TABLE IF NOT EXISTS crm_email_list_member (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    email_list_id INTEGER NOT NULL,
    contact_id INTEGER,
-   email VARCHAR(250) NOT NULL,
+   email VARCHAR(320) NOT NULL,
    first_name VARCHAR(100),
    status INTEGER DEFAULT 1 NOT NULL,
    subscribed_date TIMESTAMP WITHOUT TIME ZONE,
@@ -364,9 +365,13 @@ CREATE INDEX IF NOT EXISTS ix_crm_email_list_member_form_submission_id ON crm_em
 
 CREATE TABLE IF NOT EXISTS crm_email_message (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   idempotency_key VARCHAR(250) UNIQUE,
+   email_message_id VARCHAR(100),
+   delivered_date TIMESTAMP WITHOUT TIME ZONE,
+   bounced_date TIMESTAMP WITHOUT TIME ZONE,
    activity_id INTEGER,
    contact_id INTEGER,
-   from_address VARCHAR(250) NOT NULL,
+   from_address VARCHAR(250),
    from_name VARCHAR(100),
    to_addresses TEXT NOT NULL,
    cc_addresses TEXT,
@@ -392,6 +397,7 @@ CREATE TABLE IF NOT EXISTS crm_email_message (
    modify_date TIMESTAMP WITHOUT TIME ZONE
 );
 
+CREATE INDEX IF NOT EXISTS ix_crm_email_message_email_message_id ON crm_email_message (email_message_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_contact_id ON crm_email_message (contact_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_activity_id ON crm_email_message (activity_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_thread_id ON crm_email_message (thread_id);
@@ -455,18 +461,18 @@ CREATE TABLE IF NOT EXISTS crm_form_submission (
    client_hash VARCHAR(64),
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    form_type INTEGER NOT NULL,
-   email VARCHAR(250) NOT NULL,
+   email VARCHAR(320) NOT NULL,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    company VARCHAR(250),
    phone VARCHAR(50),
    message TEXT,
    source_url VARCHAR(1000),
-   utm_source VARCHAR(250),
-   utm_medium VARCHAR(250),
-   utm_campaign VARCHAR(250),
-   utm_term VARCHAR(250),
-   utm_content VARCHAR(250),
+   utm_source VARCHAR(500),
+   utm_medium VARCHAR(500),
+   utm_campaign VARCHAR(500),
+   utm_term VARCHAR(500),
+   utm_content VARCHAR(500),
    referrer VARCHAR(1000),
    contact_id INTEGER,
    conversion_status INTEGER DEFAULT 1 NOT NULL,
@@ -640,3 +646,10 @@ CREATE TABLE IF NOT EXISTS crm_win_loss_reason (
 );
 
 CREATE INDEX IF NOT EXISTS ix_crm_consent_record_evidence_form_submission_id ON crm_consent_record (evidence_form_submission_id);
+
+CREATE TABLE IF NOT EXISTS crm_job_state (
+   id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   name VARCHAR(250) NOT NULL UNIQUE,
+   last_success TIMESTAMP WITHOUT TIME ZONE,
+   last_full_pass TIMESTAMP WITHOUT TIME ZONE
+);

pom.xml

@@ -22,6 +22,7 @@
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
    <properties>
+      <qqq.version>4.1.0-RC.26</qqq.version> <!-- feeds qbit-build-parent's qqq-bom-pom import -->
       <revision>0.2.0-SNAPSHOT</revision>
       <maven.compiler.source>21</maven.compiler.source>
       <maven.compiler.target>21</maven.compiler.target>
@@ -33,7 +34,7 @@
    <parent>
       <groupId>com.kingsrook</groupId>
       <artifactId>qbit-build-parent</artifactId>
-      <version>2.1.2</version>
+      <version>2.2.1</version>
    </parent>
 
    <groupId>com.kingsrook.qbits</groupId>
@@ -73,10 +74,16 @@
    </scm>
 
    <dependencies>
+      <dependency>
+         <groupId>com.kingsrook.qqq</groupId>
+         <artifactId>qqq-middleware-api</artifactId>
+         <optional>true</optional>
+      </dependency>
+
       <dependency>
          <groupId>com.kingsrook.qbits</groupId>
          <artifactId>qbit-email</artifactId>
-         <version>0.1.0-RC.3</version>
+         <version>0.1.0-RC.11</version>
          <optional>true</optional>
       </dependency>
       <dependency>
@@ -102,6 +109,13 @@
          <scope>test</scope>
       </dependency>
 
+      <dependency>
+         <groupId>org.liquibase</groupId>
+         <artifactId>liquibase-core</artifactId>
+         <version>4.33.0</version>
+         <scope>test</scope>
+      </dependency>
+
       <dependency>
          <groupId>org.junit.jupiter</groupId>
          <artifactId>junit-jupiter</artifactId>
@@ -117,7 +131,35 @@
    </dependencies>
 
    <build>
+      <resources>
+         <!-- help bundles carry the artifact version (QQQ help bundle provenance) -->
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>true</filtering>
+            <includes>
+               <include>help/*.yaml</include>
+               <include>qbit-crm.properties</include>
+            </includes>
+         </resource>
+         <resource>
+            <directory>src/main/resources</directory>
+            <filtering>false</filtering>
+            <excludes>
+               <exclude>help/*.yaml</exclude>
+               <exclude>qbit-crm.properties</exclude>
+            </excludes>
+         </resource>
+      </resources>
       <plugins>
+         <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+               <systemPropertyVariables combine.children="append">
+                  <qbit.artifactVersion>${project.version}</qbit.artifactVersion>
+               </systemPropertyVariables>
+            </configuration>
+         </plugin>
          <plugin>
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-checkstyle-plugin</artifactId>
@@ -186,14 +228,14 @@
    <profiles>
       <!-- Built against qqq 4.1 (QBitMetaDataProducer). Until qbit-build-parent  -->
       <!-- imports the released 4.1 BOM, this profile is active by default and     -->
-      <!-- imports qqq-bom-pom 4.1.0-RC.6 ahead of the parent's 4.0.0 BOM.         -->
+      <!-- imports qqq-bom-pom 4.1.0-RC.7 ahead of the parent's 4.0.0 BOM.         -->
       <profile>
          <id>qqq-snapshot</id>
          <activation>
             <activeByDefault>true</activeByDefault>
          </activation>
          <properties>
-            <qqq.snapshot.version>4.1.0-RC.6</qqq.snapshot.version>
+            <qqq.snapshot.version>4.1.0-RC.26</qqq.snapshot.version>
          </properties>
          <dependencyManagement>
             <dependencies>

src/main/java/com/kingsrook/qbits/crm/CrmAppMetaData.java

@@ -30,17 +30,14 @@ import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.SourceQBitAware;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 
 
 /*******************************************************************************
  ** The CRM home and the two navigation sections. Child tables stay on records.
  *******************************************************************************/
-public final class CrmAppMetaData extends QAppMetaData implements SourceQBitAware
+public final class CrmAppMetaData
 {
-   private String sourceQBitName;
-
    public static final List<String> MAIN_TABLES = List.of("crm_contact", "crm_company", "crm_deal", "crm_activity", "crm_form_submission", "crm_email_list");
    public static final List<String> SETTINGS_TABLES = List.of("crm_pipeline", "crm_product", "crm_email_template", "crm_email_sequence",
       "crm_lead_score_rule", "crm_assignment_rule", "crm_sales_goal", "crm_currency", "crm_lifecycle_stage", "crm_lead_source",
@@ -70,7 +67,7 @@ public final class CrmAppMetaData extends QAppMetaData implements SourceQBitAwar
     *******************************************************************************/
    public static QAppMetaData build(MetaDataProducerMultiOutput output, String source)
    {
-      QAppMetaData app = new CrmAppMetaData().withSourceQBitName(source).withName("crm").withLabel("CRM").withIcon(new QIcon("contacts"))
+      QAppMetaData app = new QAppMetaData().withName("crm").withLabel("CRM").withIcon(new QIcon("contacts"))
          .withPermissionRules(CrmPermissions.hasAccessRules(CrmPermissions.BASE))
          .withWidgets(new ArrayList<>(CrmHomeWidgets.HOME))
          .withSection(mainSection())
@@ -84,34 +81,4 @@ public final class CrmAppMetaData extends QAppMetaData implements SourceQBitAwar
       }
       return (app);
    }
-
-   /*******************************************************************************
-    ** QBit provenance, until core apps implement SourceQBitAware.
-    *******************************************************************************/
-   @Override
-   public String getSourceQBitName()
-   {
-      return (sourceQBitName);
-   }
-
-
-   /*******************************************************************************
-    ** QBit provenance, until core apps implement SourceQBitAware.
-    *******************************************************************************/
-   @Override
-   public void setSourceQBitName(String sourceQBitName)
-   {
-      this.sourceQBitName = sourceQBitName;
-   }
-
-
-   /*******************************************************************************
-    ** QBit provenance, until core apps implement SourceQBitAware.
-    *******************************************************************************/
-   @Override
-   public CrmAppMetaData withSourceQBitName(String sourceQBitName)
-   {
-      setSourceQBitName(sourceQBitName);
-      return (this);
-   }
 }

src/main/java/com/kingsrook/qbits/crm/CrmIntegrations.java

@@ -0,0 +1,87 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.crm.security.CrmDataPolicy;
+import com.kingsrook.qqq.api.model.metadata.tables.ApiTableMetaData;
+import com.kingsrook.qqq.api.model.metadata.tables.ApiTableMetaDataContainer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** Optional host API publication and the core record-search contract.
+ *******************************************************************************/
+public final class CrmIntegrations
+{
+   private static final Map<String, List<String>> SEARCH_FIELDS = Map.of(
+      "crm_contact", List.of("firstName", "lastName", "email"),
+      "crm_company", List.of("name", "domain"), "crm_deal", List.of("name"),
+      "crm_activity", List.of("subject"), "crm_form_submission", List.of("email"), "crm_email_list", List.of("name"));
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmIntegrations()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Enable publication only when the host supplies both API settings.
+    *******************************************************************************/
+   public static void apply(MetaDataProducerMultiOutput output, CrmQBitConfig config) throws QException
+   {
+      if(config.getEsbDestinationName() != null)
+      {
+         throw (new QException("CRM ESB publication requires classified-value exclusion, which QQQ 4.1.0-RC.6 does not provide."));
+      }
+      boolean api = config.getApiName() != null && config.getApiVersion() != null;
+      if(api)
+      {
+         try
+         {
+            Class.forName("com.kingsrook.qqq.api.model.metadata.tables.ApiTableMetaDataContainer");
+         }
+         catch(ClassNotFoundException | LinkageError e)
+         {
+            throw (new QException("CRM API publication requires qqq-middleware-api on the host classpath.", e));
+         }
+      }
+      for(QTableMetaData table : output.getEach(QTableMetaData.class))
+      {
+         if(SEARCH_FIELDS.containsKey(table.getName()))
+         {
+            table.withSearchFields(SEARCH_FIELDS.get(table.getName()));
+         }
+         if(api && CrmDataPolicy.isPublishedTable(table.getName()))
+         {
+            ApiTableMetaDataContainer.ofOrWithNew(table).withApiTableMetaData(config.getApiName(),
+               new ApiTableMetaData().withInitialVersion(config.getApiVersion()).withIsExcluded(false));
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/CrmPresentation.java

@@ -0,0 +1,131 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.ChildRecordListRenderer;
+import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.DisplayFormat;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+
+
+/*******************************************************************************
+ ** CRM presentation shared by package-discovered tables and child widgets.
+ *******************************************************************************/
+public final class CrmPresentation
+{
+   private static final Map<String, String> LABELS = Map.ofEntries(
+      Map.entry("crm_contact", "Contacts"),
+      Map.entry("crm_company", "Companies"),
+      Map.entry("crm_deal", "Deals"),
+      Map.entry("crm_activity", "Activities"),
+      Map.entry("crm_form_submission", "Web Leads"),
+      Map.entry("crm_email_list", "Lists"),
+      Map.entry("crm_pipeline", "Pipelines"),
+      Map.entry("crm_pipeline_stage", "Pipeline Stages"),
+      Map.entry("crm_product", "Products"),
+      Map.entry("crm_email_template", "Email Templates"),
+      Map.entry("crm_email_sequence", "Email Sequences"),
+      Map.entry("crm_sequence_step", "Sequence Steps"),
+      Map.entry("crm_sequence_enrollment", "Sequence Enrollments"),
+      Map.entry("crm_lead_score_rule", "Lead Score Rules"),
+      Map.entry("crm_assignment_rule", "Assignment Rules"),
+      Map.entry("crm_assignment_rule_member", "Assignment Rule Members"),
+      Map.entry("crm_sales_goal", "Sales Goals"),
+      Map.entry("crm_currency", "Currencies"),
+      Map.entry("crm_lifecycle_stage", "Lifecycle Stages"),
+      Map.entry("crm_lead_source", "Lead Sources"),
+      Map.entry("crm_industry", "Industries"),
+      Map.entry("crm_activity_type", "Activity Types"),
+      Map.entry("crm_activity_outcome", "Activity Outcomes"),
+      Map.entry("crm_contact_role", "Contact Roles"),
+      Map.entry("crm_win_loss_reason", "Win/Loss Reasons"),
+      Map.entry("crm_consent_record", "Consent Records"),
+      Map.entry("crm_email_list_member", "List Members"),
+      Map.entry("crm_email_message", "Email Messages"),
+      Map.entry("crm_deal_contact", "Deal Contacts"),
+      Map.entry("crm_deal_product", "Deal Products"),
+      Map.entry("crm_deal_stage_history", "Deal Stage History"),
+      Map.entry("crm_activity_participant", "Activity Participants"),
+      Map.entry("crm_external_mapping", "External Mappings"),
+      Map.entry("crm_job_state", "Job State"));
+   private static final Map<String, List<String>> CHILD_FIELDS = Map.ofEntries(
+      Map.entry("crm_contact", List.of("firstName", "lastName", "email", "phone")),
+      Map.entry("crm_deal", List.of("name", "pipelineStageId", "amount", "expectedCloseDate")),
+      Map.entry("crm_activity", List.of("subject", "activityTypeId", "startDate")),
+      Map.entry("crm_form_submission", List.of("formKey", "createDate", "conversionStatus")),
+      Map.entry("crm_email_list_member", List.of("emailListId", "status")),
+      Map.entry("crm_consent_record", List.of("consentType", "status", "consentDate")),
+      Map.entry("crm_sequence_enrollment", List.of("sequenceId", "status", "enrolledDate")),
+      Map.entry("crm_email_message", List.of("subject", "status", "sentDate")),
+      Map.entry("crm_deal_contact", List.of("contactId", "contactRoleId", "isPrimary")),
+      Map.entry("crm_deal_product", List.of("productId", "quantity", "unitPrice", "totalAmount")),
+      Map.entry("crm_deal_stage_history", List.of("fromStageId", "toStageId", "transitionDate", "userId")));
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmPresentation()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Explicit labels avoid exposing technical table and user-id names.
+    *******************************************************************************/
+   public static void configureTable(QTableMetaData table)
+   {
+      table.setLabel(LABELS.get(table.getName()));
+      Map<String, String> users = Map.of("ownerUserId", "Owner", "assignedToUserId", "Assigned To",
+         "assignToUserId", "Assign To", "enrolledByUserId", "Enrolled By", "convertedByUserId", "Converted By", "userId", "User");
+      table.getFields().values().forEach(field ->
+      {
+         if(users.containsKey(field.getName()))
+         {
+            field.setLabel(users.get(field.getName()));
+         }
+      });
+      Map<String, List<String>> money = Map.of("crm_deal", List.of("amount", "amountInBaseCurrency", "weightedAmount"),
+         "crm_deal_product", List.of("unitPrice", "totalAmount"), "crm_product", List.of("unitPrice"), "crm_sales_goal", List.of("targetAmount"));
+      for(String field : money.getOrDefault(table.getName(), List.of()))
+      {
+         table.getField(field).setDisplayFormat(DisplayFormat.CURRENCY);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** RC.6 supports a per-widget field list, preserving each full child table.
+    *******************************************************************************/
+   public static void configureChildList(QWidgetMetaData widget, String childTable)
+   {
+      List<String> fields = CHILD_FIELDS.get(childTable);
+      if(fields != null)
+      {
+         widget.withDefaultValue(ChildRecordListRenderer.KEY_ONLY_INCLUDE_FIELD_NAMES, new ArrayList<>(fields));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/CrmQBitConfig.java

@@ -27,10 +27,8 @@ package com.kingsrook.qbits.crm;
 
 
 import java.util.List;
-import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitConfig;
-import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.utils.StringUtils;
 
@@ -43,6 +41,15 @@ public class CrmQBitConfig implements QBitConfig
 {
    public static final CrmQBitConfig DEFAULT_CONFIG = new CrmQBitConfig();
 
+   private String tenantSecurityKeyType;
+   private String tenantAllAccessKeyName;
+   private String apiName;
+   private String apiVersion;
+   private String esbDestinationName;
+
+   private String schedulerName;
+   private Boolean schedulesEnabled = true;
+
    private String messagingProviderName;
 
    private String publicBaseUrl;
@@ -53,8 +60,6 @@ public class CrmQBitConfig implements QBitConfig
    private Boolean                                     inferBackendNames = true;
    private Boolean                                     appEnabled = true;
    private MetaDataCustomizerInterface<QTableMetaData>  tableMetaDataCustomizer;
-   private List<QFieldMetaData>                         securityFields;
-   private List<RecordSecurityLock>                     recordSecurityLocks;
 
 
 
@@ -134,48 +139,6 @@ public class CrmQBitConfig implements QBitConfig
 
 
 
-   /*******************************************************************************
-    ** Getter for securityFields
-    *******************************************************************************/
-   public List<QFieldMetaData> getSecurityFields()
-   {
-      return (this.securityFields);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for securityFields
-    *******************************************************************************/
-   public CrmQBitConfig withSecurityFields(List<QFieldMetaData> securityFields)
-   {
-      this.securityFields = securityFields;
-      return (this);
-   }
-
-
-
-   /*******************************************************************************
-    ** Getter for recordSecurityLocks
-    *******************************************************************************/
-   public List<RecordSecurityLock> getRecordSecurityLocks()
-   {
-      return (this.recordSecurityLocks);
-   }
-
-
-
-   /*******************************************************************************
-    ** Fluent setter for recordSecurityLocks
-    *******************************************************************************/
-   public CrmQBitConfig withRecordSecurityLocks(List<RecordSecurityLock> recordSecurityLocks)
-   {
-      this.recordSecurityLocks = recordSecurityLocks;
-      return (this);
-   }
-
-
-
    /*******************************************************************************
     ** Whether to infer snake_case database column names.
     *******************************************************************************/
@@ -271,4 +234,133 @@ public class CrmQBitConfig implements QBitConfig
       return (this);
    }
 
+   /*******************************************************************************
+    ** Scheduler configuration: schedulerName.
+    *******************************************************************************/
+   public String getSchedulerName()
+   {
+      return (schedulerName);
+   }
+
+   /*******************************************************************************
+    ** Configure schedulerName.
+    *******************************************************************************/
+   public CrmQBitConfig withSchedulerName(String schedulerName)
+   {
+      this.schedulerName = schedulerName;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Scheduler configuration: schedulesEnabled.
+    *******************************************************************************/
+   public Boolean getSchedulesEnabled()
+   {
+      return (schedulesEnabled);
+   }
+
+   /*******************************************************************************
+    ** Configure schedulesEnabled.
+    *******************************************************************************/
+   public CrmQBitConfig withSchedulesEnabled(Boolean schedulesEnabled)
+   {
+      this.schedulesEnabled = schedulesEnabled;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Getter for tenantSecurityKeyType.
+    *******************************************************************************/
+   public String getTenantSecurityKeyType()
+   {
+      return (tenantSecurityKeyType);
+   }
+
+
+   /*******************************************************************************
+    ** Configure tenantSecurityKeyType; null disables the optional integration.
+    *******************************************************************************/
+   public CrmQBitConfig withTenantSecurityKeyType(String tenantSecurityKeyType)
+   {
+      this.tenantSecurityKeyType = tenantSecurityKeyType;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for tenantAllAccessKeyName.
+    *******************************************************************************/
+   public String getTenantAllAccessKeyName()
+   {
+      return (tenantAllAccessKeyName);
+   }
+
+
+   /*******************************************************************************
+    ** Configure tenantAllAccessKeyName; null disables the optional integration.
+    *******************************************************************************/
+   public CrmQBitConfig withTenantAllAccessKeyName(String tenantAllAccessKeyName)
+   {
+      this.tenantAllAccessKeyName = tenantAllAccessKeyName;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for apiName.
+    *******************************************************************************/
+   public String getApiName()
+   {
+      return (apiName);
+   }
+
+
+   /*******************************************************************************
+    ** Configure apiName; null disables the optional integration.
+    *******************************************************************************/
+   public CrmQBitConfig withApiName(String apiName)
+   {
+      this.apiName = apiName;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for apiVersion.
+    *******************************************************************************/
+   public String getApiVersion()
+   {
+      return (apiVersion);
+   }
+
+
+   /*******************************************************************************
+    ** Configure apiVersion; null disables the optional integration.
+    *******************************************************************************/
+   public CrmQBitConfig withApiVersion(String apiVersion)
+   {
+      this.apiVersion = apiVersion;
+      return (this);
+   }
+
+
+   /*******************************************************************************
+    ** Getter for esbDestinationName.
+    *******************************************************************************/
+   public String getEsbDestinationName()
+   {
+      return (esbDestinationName);
+   }
+
+
+   /*******************************************************************************
+    ** Configure esbDestinationName; null disables the optional integration.
+    *******************************************************************************/
+   public CrmQBitConfig withEsbDestinationName(String esbDestinationName)
+   {
+      this.esbDestinationName = esbDestinationName;
+      return (this);
+   }
+
+
 }

src/main/java/com/kingsrook/qbits/crm/CrmQBitProducer.java

@@ -26,20 +26,31 @@
 package com.kingsrook.qbits.crm;
 
 
+import java.io.IOException;
+import java.io.InputStream;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
+import java.util.Properties;
 import com.kingsrook.qbits.crm.activities.customizers.ActivityLastDateCustomizer;
 import com.kingsrook.qbits.crm.activities.model.Activity;
+import com.kingsrook.qbits.crm.core.customizers.CurrencyRateDateCustomizer;
 import com.kingsrook.qbits.crm.core.customizers.FormSubmissionAutoLinkCustomizer;
 import com.kingsrook.qbits.crm.core.model.Company;
 import com.kingsrook.qbits.crm.core.model.Contact;
+import com.kingsrook.qbits.crm.core.model.Currency;
 import com.kingsrook.qbits.crm.core.model.FormSubmission;
 import com.kingsrook.qbits.crm.deals.customizers.DealInitializationCustomizer;
 import com.kingsrook.qbits.crm.deals.customizers.DealProductRecalculationCustomizer;
 import com.kingsrook.qbits.crm.deals.customizers.DealStageChangeCustomizer;
 import com.kingsrook.qbits.crm.deals.model.Deal;
 import com.kingsrook.qbits.crm.deals.model.DealProduct;
+import com.kingsrook.qbits.crm.email.CrmEmailProcessIdentity;
+import com.kingsrook.qbits.crm.health.CrmHealthChecks;
+import com.kingsrook.qbits.crm.scoring.AutoAssignCustomizer;
+import com.kingsrook.qbits.crm.security.CrmDataPolicy;
 import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qbits.crm.security.CrmRelationshipValidator;
 import com.kingsrook.qbits.crm.widgets.CrmWidgetMetaData;
 import com.kingsrook.qqq.backend.core.actions.customizers.MultiCustomizer;
 import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers;
@@ -54,13 +65,18 @@ import com.kingsrook.qqq.backend.core.model.metadata.audits.AuditLevel;
 import com.kingsrook.qqq.backend.core.model.metadata.audits.QAuditRules;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
 import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReferenceWithProperties;
+import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeature;
+import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeaturesMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordOwnership;
 import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
 import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
 import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitMetaDataProducer;
+import com.kingsrook.qqq.backend.core.model.metadata.scheduleing.QScheduleMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
@@ -74,12 +90,40 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
 {
    public static final String GROUP_ID    = "com.kingsrook.qbits";
    public static final String ARTIFACT_ID = "crm";
-   public static final String VERSION     = "0.2.0-SNAPSHOT";
+   public static final String VERSION     = loadVersion();
 
    private CrmQBitConfig qBitConfig;
 
 
 
+   /*******************************************************************************
+    ** Read the artifact version from the Maven-filtered properties resource.
+    *******************************************************************************/
+   private static String loadVersion()
+   {
+      try(InputStream inputStream = CrmQBitProducer.class.getClassLoader().getResourceAsStream("qbit-crm.properties"))
+      {
+         if(inputStream == null)
+         {
+            throw new IllegalStateException("Missing qbit-crm.properties; build with Maven to provide the artifact version");
+         }
+         Properties properties = new Properties();
+         properties.load(inputStream);
+         String version = properties.getProperty("version");
+         if(version == null || version.isBlank() || version.contains("${"))
+         {
+            throw new IllegalStateException("Missing or unfiltered version in qbit-crm.properties; build with Maven to provide the artifact version");
+         }
+         return (version);
+      }
+      catch(IOException e)
+      {
+         throw new IllegalStateException("Could not read artifact version from qbit-crm.properties", e);
+      }
+   }
+
+
+
    /*******************************************************************************
     ** Produce the QBitMetaData for the CRM QBit.
     *******************************************************************************/
@@ -106,18 +150,22 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
       {
          join.setName(snakeCase(join.getName()));
       }
+      CrmDataPolicy.apply(metaDataProducerMultiOutput, qInstance, qBitConfig);
+      CrmIntegrations.apply(metaDataProducerMultiOutput, qBitConfig);
+      CrmHealthChecks.register(qInstance, qBitConfig);
       for(QWidgetMetaData widget : metaDataProducerMultiOutput.getEach(QWidgetMetaData.class))
       {
          widget.setName(snakeCase(widget.getName()));
          QCodeReference permissionChecker = widget.getPermissionRules() == null ? null : widget.getPermissionRules().getCustomPermissionChecker();
          widget.setPermissionRules(CrmPermissions.hasAccessRules(CrmPermissions.BASE).withCustomPermissionChecker(permissionChecker));
-         widget.setGridColumns(12);
+         widget.setGridColumns(com.kingsrook.qbits.crm.widgets.CrmHomeWidgets.TODAY.contains(widget.getName()) ? 4 : 12);
          if(widget.getDefaultValues() != null && widget.getDefaultValues().get("joinName") instanceof String joinName)
          {
             String normalizedJoinName = snakeCase(joinName);
             widget.withDefaultValue("joinName", normalizedJoinName);
             QJoinMetaData join = metaDataProducerMultiOutput.getEach(QJoinMetaData.class).stream()
                .filter(candidate -> candidate.getName().equals(normalizedJoinName)).findFirst().orElseThrow();
+            CrmPresentation.configureChildList(widget, join.getRightTable());
             QTableMetaData parent = metaDataProducerMultiOutput.get(QTableMetaData.class, join.getLeftTable());
             boolean alreadyAttached = parent.getSections() != null && parent.getSections().stream()
                .anyMatch(section -> section.getWidgetName() != null && snakeCase(section.getWidgetName()).equals(widget.getName()));
@@ -129,8 +177,6 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
          }
       }
 
-      metaDataProducerMultiOutput.get(QTableMetaData.class, "crm_form_submission").setLabel("Web Leads");
-      metaDataProducerMultiOutput.get(QTableMetaData.class, "crm_email_list").setLabel("Lists");
       metaDataProducerMultiOutput.get(QTableMetaData.class, Contact.TABLE_NAME).withSection(
          new QFieldSection("crm_contact_timeline", "Timeline", new QIcon("history"), Tier.T2, List.of())
             .withWidgetName("crm_contact_timeline"));
@@ -139,6 +185,12 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
       {
          process.setPermissionRules(CrmPermissions.processRules(process.getName()));
          process.setSourceQBitName(getQBitMetaData().getName());
+         Integer seconds = Map.of("crm_process_sequence_steps", 300, "crm_calculate_lead_scores", 3600,
+            "crm_sync_email_delivery", 900, "crm_expire_consents", 86400).get(process.getName());
+         if(seconds != null && qBitConfig.getSchedulerName() != null && !Boolean.FALSE.equals(qBitConfig.getSchedulesEnabled()))
+         {
+            process.withSchedule(new QScheduleMetaData().withSchedulerName(qBitConfig.getSchedulerName()).withRepeatSeconds(seconds));
+         }
       }
 
       /////////////////////////////////////////////////////////////////////////
@@ -147,6 +199,16 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
       for(QTableMetaData table : metaDataProducerMultiOutput.getEach(QTableMetaData.class))
       {
          String tableName = table.getName();
+         CrmPresentation.configureTable(table);
+         if(tableName.equals(Contact.TABLE_NAME))
+         {
+            addOrComposeCustomizer(table, TableCustomizers.POST_QUERY_RECORD, new QCodeReference(com.kingsrook.qbits.crm.core.customizers.ContactLabelCustomizer.class));
+         }
+         if(tableName.equals(Deal.TABLE_NAME) || tableName.equals(Activity.TABLE_NAME))
+         {
+            addOrComposeCustomizer(table, TableCustomizers.PRE_INSERT_RECORD, new QCodeReference(CrmRelationshipValidator.class));
+            addOrComposeCustomizer(table, TableCustomizers.PRE_UPDATE_RECORD, new QCodeReference(CrmRelationshipValidator.class));
+         }
          table.setPermissionRules(CrmPermissions.tableRules(tableName));
          table.setSourceQBitName(getQBitMetaData().getName());
          if(table.getSections() != null)
@@ -171,11 +233,26 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
             || tableName.equals(Deal.TABLE_NAME) || tableName.equals(Activity.TABLE_NAME))
          {
             table.withAuditRules(new QAuditRules().withAuditLevel(AuditLevel.FIELD));
+            RecordFeaturesMetaData features = RecordFeaturesMetaData.ofOrWithNew(table)
+               .withOwnership(new RecordOwnership().withOwnerFieldName("ownerUserId"));
+            for(RecordFeature feature : List.of(RecordFeature.TAGS, RecordFeature.COMMENTS, RecordFeature.ATTACHMENTS,
+               RecordFeature.FOLLOW, RecordFeature.TIMELINE, RecordFeature.RECENTS, RecordFeature.FAVORITES))
+            {
+               features.withEnabled(feature, true);
+            }
+            if(!tableName.equals(Activity.TABLE_NAME))
+            {
+               features.withEnabled(RecordFeature.TASKS, true).withEnabled(RecordFeature.ASSIGNMENT, true);
+            }
          }
 
          ///////////////////////////////////////////////////////////////
          // wire activity timestamp propagation                       //
          ///////////////////////////////////////////////////////////////
+         if(tableName.equals(Contact.TABLE_NAME) || tableName.equals(Deal.TABLE_NAME))
+         {
+            addOrComposeCustomizer(table, TableCustomizers.POST_INSERT_RECORD, new QCodeReference(AutoAssignCustomizer.class));
+         }
          if(tableName.equals(Activity.TABLE_NAME))
          {
             addOrComposeCustomizer(table, TableCustomizers.POST_INSERT_RECORD, new QCodeReference(ActivityLastDateCustomizer.class));
@@ -190,6 +267,15 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
             addOrComposeCustomizer(table, TableCustomizers.POST_INSERT_RECORD, new QCodeReference(DealInitializationCustomizer.class));
          }
 
+         ///////////////////////////////////////////////////////////////
+         // stamp the exchange-rate date when a rate is set or changed  //
+         ///////////////////////////////////////////////////////////////
+         if(tableName.equals(Currency.TABLE_NAME))
+         {
+            addOrComposeCustomizer(table, TableCustomizers.PRE_INSERT_RECORD, new QCodeReference(CurrencyRateDateCustomizer.OnInsert.class));
+            addOrComposeCustomizer(table, TableCustomizers.PRE_UPDATE_RECORD, new QCodeReference(CurrencyRateDateCustomizer.OnUpdate.class));
+         }
+
          ///////////////////////////////////////////////////////////////
          // wire deal product recalculation                           //
          ///////////////////////////////////////////////////////////////
@@ -324,7 +410,15 @@ public class CrmQBitProducer implements QBitMetaDataProducer<CrmQBitConfig>
          .withSourceQBitName(getQBitMetaData().getName()));
       output.add(new QAlertTypeMetaData().withName("crm.email.unavailable").withLabel("Email unavailable")
          .withSourceQBitName(getQBitMetaData().getName()));
+      for(String notification : List.of("crm.lead.assigned", "crm.deal.won", "crm.deal.rotting", "crm.task.due"))
+      {
+         output.add(new QAlertTypeMetaData().withName(notification).withLabel(notification)
+            .withDefaultSeverity(AlertSeverity.INFO).withSourceQBitName(getQBitMetaData().getName()));
+      }
+      qInstance.withProcessLifecycleListener(new QCodeReference(CrmEmailProcessIdentity.class));
       registerHooks(qInstance);
+      // Registration is metadata-only; core startup sync guards hosts without helpContent.
+      HelpBundles.register(qInstance, "help/qbit-crm.yaml");
       return (output);
    }
 

src/main/java/com/kingsrook/qbits/crm/actions/CrmAction.java

@@ -32,6 +32,7 @@ import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
 import com.kingsrook.qbits.crm.activities.processes.LogActivityProcess;
+import com.kingsrook.qbits.crm.api.CrmApi;
 import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
 import com.kingsrook.qbits.crm.core.processes.ConvertFormToContactProcess;
 import com.kingsrook.qbits.crm.core.processes.GdprAnonymizeContactProcess;
@@ -42,6 +43,8 @@ import com.kingsrook.qbits.crm.core.processes.UnsubscribeFromListProcess;
 import com.kingsrook.qbits.crm.deals.processes.CloneDealProcess;
 import com.kingsrook.qbits.crm.deals.processes.ConvertLeadProcess;
 import com.kingsrook.qbits.crm.deals.processes.ManageContactOnDealProcess;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.email.CrmEmails;
 import com.kingsrook.qbits.crm.email.processes.EnrollInSequenceProcess;
 import com.kingsrook.qbits.crm.email.processes.UnenrollFromSequenceProcess;
 import com.kingsrook.qbits.crm.scoring.processes.AutoAssignProcess;
@@ -84,7 +87,7 @@ public final class CrmAction
 {
    private static final QLogger LOG = QLogger.getLogger(CrmAction.class);
 
-   public static final String EMAIL_WARNING = "Email sending arrives with the email transport";
+
 
    /*******************************************************************************
     ** Utility holder.
@@ -162,6 +165,14 @@ public final class CrmAction
     *******************************************************************************/
    public static class Transform extends AbstractTransformStep implements ProcessSummaryProviderInterface
    {
+      /*******************************************************************************
+       ** Resolve the host transport; tests may supply a fake.
+       *******************************************************************************/
+      protected CrmEmailTransport emailTransport() throws QException
+      {
+         return (new CrmEmailTransport(CrmApi.config()));
+      }
+
       private final Map<String, ProcessSummaryLine> lines = new LinkedHashMap<>();
       private final Map<String, List<Serializable>> duplicateGroups = new LinkedHashMap<>();
       private List<QRecord> pair;
@@ -190,7 +201,7 @@ public final class CrmAction
             try
             {
                QRecord row = requireRow(action, input, id);
-               String reason = check(action, input, row);
+               String reason = check(action, input, row, action.operation().equals("email") ? emailTransport() : null);
                if(reason != null)
                {
                   add(lines, Status.WARNING, reason, reason, id);
@@ -253,6 +264,14 @@ public final class CrmAction
     *******************************************************************************/
    public static class Load extends AbstractLoadStep implements ProcessSummaryProviderInterface
    {
+      /*******************************************************************************
+       ** Resolve the host transport; tests may supply a fake.
+       *******************************************************************************/
+      protected CrmEmailTransport emailTransport() throws QException
+      {
+         return (new CrmEmailTransport(CrmApi.config()));
+      }
+
       private final Map<String, ProcessSummaryLine> lines = new LinkedHashMap<>();
       private boolean duplicates;
 
@@ -267,14 +286,14 @@ public final class CrmAction
             try
             {
                QRecord row = requireRow(action, input, id);
-               String reason = check(action, input, row);
+               String reason = check(action, input, row, action.operation().equals("email") ? emailTransport() : null);
                if(reason != null)
                {
                   add(lines, Status.WARNING, reason, reason, id);
                   continue;
                }
                row.setValue("mergeSecondaryId", reviewed.getValue("mergeSecondaryId"));
-               String skipped = perform(action, input, row);
+               String skipped = perform(action, input, row, action.operation().equals("email") ? emailTransport() : null);
                if(skipped == null)
                {
                   add(lines, Status.OK, "will be " + action.past(), "was " + action.past(), id);
@@ -345,7 +364,7 @@ public final class CrmAction
    /*******************************************************************************
     ** Shared read-only checks for Review and Result.
     *******************************************************************************/
-   private static String check(CrmActions.Action action, RunBackendStepInput input, QRecord row) throws QException
+   private static String check(CrmActions.Action action, RunBackendStepInput input, QRecord row, CrmEmailTransport transport) throws QException
    {
       for(QFieldMetaData field : CrmActions.inputFields(action))
       {
@@ -365,15 +384,7 @@ public final class CrmAction
       switch(action.operation())
       {
          case "email":
-            try
-            {
-               Class.forName("com.kingsrook.qbits.crm.email.CrmEmailTransport");
-               return ("Email transport is present; sending integration is not configured for this action yet");
-            }
-            catch(ClassNotFoundException expected)
-            {
-               return (EMAIL_WARNING);
-            }
+            return (CrmEmails.skipReason(row, transport));
          case "subscribe", "unsubscribe":
             if(!StringUtils.hasContent(row.getValueString("email")))
             {
@@ -479,7 +490,7 @@ public final class CrmAction
    /*******************************************************************************
     ** Invoke the existing business operations only at Load time.
     *******************************************************************************/
-   private static String perform(CrmActions.Action action, RunBackendStepInput input, QRecord row) throws QException
+   private static String perform(CrmActions.Action action, RunBackendStepInput input, QRecord row, CrmEmailTransport transport) throws QException
    {
       RunBackendStepInput call = new RunBackendStepInput().withProcessName(input.getProcessName()).withValues(new HashMap<>());
       for(QFieldMetaData field : CrmActions.inputFields(action))
@@ -494,6 +505,16 @@ public final class CrmAction
       RunBackendStepOutput result = new RunBackendStepOutput();
       switch(action.operation())
       {
+         case "email" ->
+         {
+            String processUUID = input.getValueString("crmEmailProcessUUID");
+            if(processUUID == null)
+            {
+               throw (new QUserFacingException("Email process identity is missing; start the Send Email action again"));
+            }
+            CrmEmails.send(transport, row, input.getValueInteger("emailTemplateId"), input.getValueString("subject"), input.getValueString("body"),
+               "email", id + ":" + processUUID, null);
+         }
          case "assign" -> update(action.table(), new QRecord().withValue("id", id).withValue("ownerUserId", input.getValue("newOwnerUserId")));
          case "auto" ->
          {

src/main/java/com/kingsrook/qbits/crm/actions/CrmActions.java

@@ -148,6 +148,12 @@ public class CrmActions implements MetaDataProducerInterface<MetaDataProducerMul
       List<QFieldMetaData> fields = new ArrayList<>();
       switch(action.operation())
       {
+         case "email" ->
+         {
+            fields.add(field("emailTemplateId", "Template", QFieldType.INTEGER, "crm_email_template").withIsRequired(false));
+            fields.add(field("subject", "Subject", QFieldType.STRING, null).withIsRequired(false));
+            fields.add(field("body", "Body", QFieldType.TEXT, null).withIsRequired(false));
+         }
          case "assign" -> fields.add(field("newOwnerUserId", "Owner", QFieldType.STRING, null));
          case "subscribe", "unsubscribe" -> fields.add(field("emailListId", "List", QFieldType.INTEGER, "crm_email_list"));
          case "enroll", "unenroll" -> fields.add(field("sequenceId", "Sequence", QFieldType.INTEGER, "crm_email_sequence"));

src/main/java/com/kingsrook/qbits/crm/api/CrmIntakeApi.java

@@ -27,7 +27,6 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Objects;
 import com.kingsrook.qbits.crm.CrmQBitConfig;
-import com.kingsrook.qbits.crm.CrmSessionUtils;
 import com.kingsrook.qbits.crm.core.model.enums.CrmAssignableEntity;
 import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
 import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
@@ -288,13 +287,14 @@ public class CrmIntakeApi
       QRecord contact;
       if(contacts.isEmpty())
       {
-         String source = request.utmSource() == null || request.utmSource().isBlank() ? "Website" : request.utmSource();
+         String source = request.utmSource() == null || request.utmSource().isBlank() ? "Website" : request.utmSource().strip();
+         source = source.length() > 100 ? source.substring(0, 100) : source;
          List<QRecord> sources = store.by("crm_lead_source", "name", source);
          QRecord leadSource = sources.isEmpty() ? store.insert("crm_lead_source", new QRecord().withValue("name", source).withValue("sortOrder", 0)) : sources.get(0);
          List<QRecord> stages = store.by("crm_lifecycle_stage", "name", "Lead");
          contact = store.insert("crm_contact", new QRecord().withValue("email", normalize(request.email()))
             .withValue("firstName", name(request.firstName())).withValue("lastName", name(request.lastName()))
-            .withValue("phone", request.phone()).withValue("ownerUserId", CrmSessionUtils.getCurrentUserId())
+            .withValue("phone", request.phone()).withValue("ownerUserId", null)
             .withValue("leadSourceId", leadSource.getValueInteger("id")).withValue("lifecycleStageId", stages.isEmpty() ? null : stages.get(0).getValueInteger("id")));
       }
       else
@@ -323,7 +323,7 @@ public class CrmIntakeApi
       }
       update.withValue("lastTouchDate", Instant.now());
       store.update("crm_contact", update);
-      if(contacts.isEmpty() && isUnassigned(contact.getValueString("ownerUserId")))
+      if(contacts.isEmpty() && isUnassigned(store.get("crm_contact", contact.getValueInteger("id")).getValueString("ownerUserId")))
       {
          CrmAutoAssign.assign(CrmAssignableEntity.CONTACT, contact.getValueInteger("id"));
       }
@@ -395,6 +395,6 @@ public class CrmIntakeApi
     *******************************************************************************/
    private String name(String value)
    {
-      return (value == null || value.isBlank() ? "Not provided" : value);
+      return (value == null || value.isBlank() ? null : value.strip());
    }
 }

src/main/java/com/kingsrook/qbits/crm/bulkload/CrmBulkLoadProfiles.java

@@ -0,0 +1,86 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.bulkload;
+
+
+import java.io.IOException;
+import java.io.InputStream;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.savedbulkloadprofiles.SavedBulkLoadProfile;
+import com.kingsrook.qqq.backend.core.processes.implementations.bulk.insert.model.BulkLoadProfile;
+
+
+/*******************************************************************************
+ ** Starter mappings for the host's core bulk loader. The host owns its tables.
+ *******************************************************************************/
+public final class CrmBulkLoadProfiles
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmBulkLoadProfiles()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Call once during host startup, after core profile tables are installed.
+    ** Existing profiles, including user edits, are preserved by label.
+    *******************************************************************************/
+   public static void ensure() throws QException
+   {
+      if(QContext.getQInstance().getTable(SavedBulkLoadProfile.TABLE_NAME) == null)
+      {
+         return;
+      }
+      try(InputStream stream = CrmBulkLoadProfiles.class.getResourceAsStream("/bulkload/crm-profiles.json"))
+      {
+         ObjectMapper mapper = new ObjectMapper();
+         for(JsonNode profile : mapper.readTree(stream))
+         {
+            String label = profile.get("label").asText();
+            if(!new QueryAction().execute(new QueryInput(SavedBulkLoadProfile.TABLE_NAME).withFilter(new QQueryFilter(
+               new QFilterCriteria("label", QCriteriaOperator.EQUALS, label)).withLimit(1))).getRecords().isEmpty())
+            {
+               continue;
+            }
+            BulkLoadProfile mapping = mapper.treeToValue(profile.get("mapping"), BulkLoadProfile.class);
+            CrmRecords.insert(SavedBulkLoadProfile.TABLE_NAME, new QRecord().withValue("label", label)
+               .withValue("tableName", profile.get("tableName").asText()).withValue("isBulkEdit", false)
+               .withValue("mappingJson", mapper.writeValueAsString(mapping)));
+         }
+      }
+      catch(IOException | IllegalArgumentException e)
+      {
+         throw (new QException("Could not load CRM bulk-load profiles", e));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/core/CrmRecords.java

@@ -0,0 +1,72 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.core;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Checked writes for background work: record errors must not advance checkpoints.
+ *******************************************************************************/
+public final class CrmRecords
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmRecords()
+   {
+   }
+
+   /*******************************************************************************
+    ** Insert and require a successful persisted row.
+    *******************************************************************************/
+   public static QRecord insert(String table, QRecord row) throws QException
+   {
+      return (check(new InsertAction().execute(new InsertInput(table).withRecord(row)).getRecords()));
+   }
+
+   /*******************************************************************************
+    ** Update and require a successful persisted row.
+    *******************************************************************************/
+   public static QRecord update(String table, QRecord row) throws QException
+   {
+      return (check(new UpdateAction().execute(new UpdateInput(table).withRecord(row)).getRecords()));
+   }
+
+   /*******************************************************************************
+    ** DML errors are failed work, never successful job progress.
+    *******************************************************************************/
+   private static QRecord check(List<QRecord> rows) throws QException
+   {
+      if(rows.isEmpty() || rows.stream().anyMatch(row -> row.getErrors() != null && !row.getErrors().isEmpty()))
+      {
+         throw (new QException("CRM write was rejected"));
+      }
+      return (rows.getFirst());
+   }
+}

src/main/java/com/kingsrook/qbits/crm/core/customizers/ContactLabelCustomizer.java

@@ -0,0 +1,73 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package com.kingsrook.qbits.crm.core.customizers;
+
+
+import java.util.List;
+import java.util.Objects;
+import com.kingsrook.qbits.crm.core.model.Contact;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPostQueryCustomizer;
+import com.kingsrook.qqq.backend.core.actions.permissions.FieldSecurityLockHelper;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** RC.6 recordLabelFormat is printf-only; preserve a computed query/get label.
+ *******************************************************************************/
+public class ContactLabelCustomizer extends AbstractPostQueryCustomizer
+{
+   /*******************************************************************************
+    ** Keep missing names absent in storage while giving records useful labels.
+    *******************************************************************************/
+   @Override
+   public List<QRecord> apply(List<QRecord> records)
+   {
+      for(QRecord record : records)
+      {
+         QRecord visible = new QRecord().withValue("id", record.getValue("id"));
+         for(String name : List.of("firstName", "lastName", "email"))
+         {
+            var field = QContext.getQInstance().getTable(Contact.TABLE_NAME).getField(name);
+            if(FieldSecurityLockHelper.isFieldAccessible(field)
+               && !(input != null && input.getShouldOmitHiddenFields() && field.getIsHidden())
+               && !(input != null && input.getShouldMaskPasswords() && field.getType().needsMasked()))
+            {
+               visible.setValue(name, record.getValue(name));
+            }
+         }
+         record.setRecordLabel(label(visible));
+      }
+      return (records);
+   }
+
+
+   /*******************************************************************************
+    ** Prefer the supplied name, then email, then the record identifier.
+    *******************************************************************************/
+   public static String label(QRecord record)
+   {
+      String name = (Objects.toString(record.getValue("firstName"), "").strip() + " "
+         + Objects.toString(record.getValue("lastName"), "").strip()).strip();
+      return (name.isBlank() ? Objects.toString(record.getValue("email"), Objects.toString(record.getValue("id"), "Contact")) : name);
+   }
+}

src/main/java/com/kingsrook/qbits/crm/core/customizers/CurrencyRateDateCustomizer.java

@@ -0,0 +1,117 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.core.customizers;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreInsertCustomizer;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreUpdateCustomizer;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.utils.ValueUtils;
+
+
+/*******************************************************************************
+ ** Stamps crm_currency.rateLastUpdatedDate whenever a rate is set or changed, so
+ ** the date says when the exchange rate was last touched. Editing only the name,
+ ** symbol or active flag leaves it alone.
+ *******************************************************************************/
+public final class CurrencyRateDateCustomizer
+{
+   public static final String RATE_FIELD = "exchangeRateToBase";
+   public static final String DATE_FIELD = "rateLastUpdatedDate";
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CurrencyRateDateCustomizer()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** A new currency has a rate from the moment it exists.
+    *******************************************************************************/
+   public static class OnInsert extends AbstractPreInsertCustomizer
+   {
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public List<QRecord> apply(List<QRecord> records) throws QException
+      {
+         Instant now = Instant.now();
+         for(QRecord record : records)
+         {
+            record.setValue(DATE_FIELD, now);
+         }
+         return (records);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** An update that carries a different rate than the stored one moves the date.
+    *******************************************************************************/
+   public static class OnUpdate extends AbstractPreUpdateCustomizer
+   {
+      /*******************************************************************************
+       **
+       *******************************************************************************/
+      @Override
+      public List<QRecord> apply(List<QRecord> records) throws QException
+      {
+         if(isPreview || oldRecordList == null)
+         {
+            return (records);
+         }
+
+         Instant now = Instant.now();
+         for(QRecord record : records)
+         {
+            QRecord oldRecord = getOldRecordMap().get(record.getValue("id"));
+            if(oldRecord != null && record.getValues().containsKey(RATE_FIELD)
+               && !sameRate(ValueUtils.getValueAsBigDecimal(record.getValue(RATE_FIELD)), ValueUtils.getValueAsBigDecimal(oldRecord.getValue(RATE_FIELD))))
+            {
+               record.setValue(DATE_FIELD, now);
+            }
+         }
+         return (records);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Numeric equality, so 1 and 1.000000 are the same rate.
+    *******************************************************************************/
+   static boolean sameRate(BigDecimal a, BigDecimal b)
+   {
+      return (a == null ? b == null : b != null && a.compareTo(b) == 0);
+   }
+
+}

src/main/java/com/kingsrook/qbits/crm/core/model/Company.java

@@ -29,7 +29,6 @@ package com.kingsrook.qbits.crm.core.model;
 import java.math.BigDecimal;
 import java.time.Instant;
 import java.util.List;
-import com.kingsrook.qbits.crm.CrmQBitConfig;
 import com.kingsrook.qbits.crm.activities.model.Activity;
 import com.kingsrook.qbits.crm.core.model.enums.CrmCompanyType;
 import com.kingsrook.qbits.crm.deals.model.Deal;
@@ -46,13 +45,10 @@ import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.Child
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildRecordListWidget;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildTable;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProductionContext;
-import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.SectionFactory;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
-import com.kingsrook.qqq.backend.core.utils.collections.MutableList;
 
 
 /*******************************************************************************
@@ -108,30 +104,7 @@ public class Company extends QRecordEntity
             .withSection(SectionFactory.defaultT2("description"))
             .withSection(SectionFactory.defaultT3("lastActivityDate", "lastContactedDate", "createDate", "modifyDate"));
 
-         ///////////////////////////////////////////////////////////////
-         // inject security fields and locks from CrmQBitConfig      //
-         ///////////////////////////////////////////////////////////////
-         CrmQBitConfig config = (CrmQBitConfig) QBitProductionContext.peekQBitConfig();
-         if(config != null)
-         {
-            if(config.getSecurityFields() != null)
-            {
-               t1Section.setFieldNames(new MutableList<>(t1Section.getFieldNames()));
-               for(QFieldMetaData fieldMetaData : config.getSecurityFields())
-               {
-                  table.addField(fieldMetaData.clone());
-                  t1Section.getFieldNames().add(fieldMetaData.getName());
-               }
-            }
 
-            if(config.getRecordSecurityLocks() != null)
-            {
-               for(RecordSecurityLock lock : config.getRecordSecurityLocks())
-               {
-                  table.withRecordSecurityLock(lock);
-               }
-            }
-         }
 
          return (table);
       }

src/main/java/com/kingsrook/qbits/crm/core/model/ConsentRecord.java

@@ -28,9 +28,11 @@ package com.kingsrook.qbits.crm.core.model;
 
 import java.time.Instant;
 import java.util.List;
+import java.util.Set;
 import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
 import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
 import com.kingsrook.qbits.crm.core.model.enums.CrmLegalBasis;
+import com.kingsrook.qbits.crm.privacy.CrmPersonalData.ErasureFlag;
 import com.kingsrook.qqq.backend.core.actions.ai.AiFieldMetaData;
 import com.kingsrook.qqq.backend.core.actions.ai.DataClassification;
 import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreDeleteCustomizer;
@@ -111,6 +113,12 @@ public class ConsentRecord extends QRecordEntity
       @Override
       public List<QRecord> apply(List<QRecord> records) throws QException
       {
+         if(updateInput != null && updateInput.hasFlag(ErasureFlag.REDACT_CONSENT)
+            && records.stream().allMatch(row -> Set.of("id", "consentText").containsAll(row.getValues().keySet())
+               && "erased".equals(row.getValueString("consentText"))))
+         {
+            return (records);
+         }
          throw new QUserFacingException("Consent records cannot be modified or deleted");
       }
    }

src/main/java/com/kingsrook/qbits/crm/core/model/Contact.java

@@ -28,7 +28,6 @@ package com.kingsrook.qbits.crm.core.model;
 
 import java.time.Instant;
 import java.util.List;
-import com.kingsrook.qbits.crm.CrmQBitConfig;
 import com.kingsrook.qbits.crm.activities.model.Activity;
 import com.kingsrook.qbits.crm.deals.model.Deal;
 import com.kingsrook.qbits.crm.email.model.EmailMessage;
@@ -46,13 +45,10 @@ import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.Child
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildRecordListWidget;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildTable;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProductionContext;
-import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.SectionFactory;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
-import com.kingsrook.qqq.backend.core.utils.collections.MutableList;
 
 
 /*******************************************************************************
@@ -105,51 +101,25 @@ public class Contact extends QRecordEntity
       @Override
       public QTableMetaData customizeMetaData(QInstance qInstance, QTableMetaData table) throws QException
       {
-         QFieldSection t1Section = SectionFactory.defaultT1("id", "firstName", "lastName", "email", "phone");
+         QFieldSection t1Section = SectionFactory.defaultT1("firstName", "lastName", "email", "phone");
 
          table
             .withIcon(new QIcon().withName("person"))
-            .withRecordLabelFormat("%s %s")
-            .withRecordLabelFields("firstName", "lastName")
+            .withRecordLabelFormat(null)
+            .withRecordLabelFields(List.of())
             .withSection(t1Section)
             .withSection(new QFieldSection("details", new QIcon().withName("info"), Tier.T2,
                List.of("companyId", "jobTitle", "department", "lifecycleStageId", "leadSourceId",
-                  "ownerUserId", "leadScore", "timezone", "preferredLanguage")))
-            .withSection(new QFieldSection("online", new QIcon().withName("language"), Tier.T2,
-               List.of("secondaryEmail", "mobilePhone", "website", "linkedinUrl")))
-            .withSection(new QFieldSection("address", new QIcon().withName("location_on"), Tier.T2,
-               List.of("addressLine1", "addressLine2", "city", "state", "postalCode", "country")))
-            .withSection(new QFieldSection("communication", new QIcon().withName("settings"), Tier.T2,
-               List.of("doNotEmail", "doNotCall", "unsubscribeDate")))
+                  "ownerUserId", "leadScore", "timezone", "preferredLanguage", "description")))
+            .withSection(new QFieldSection("contactInformation", "Contact Information", new QIcon("contact_mail"), Tier.T2,
+               List.of("secondaryEmail", "mobilePhone", "website", "linkedinUrl", "addressLine1", "addressLine2", "city", "state", "postalCode", "country",
+                  "doNotEmail", "doNotCall", "unsubscribeDate")))
             .withSection(new QFieldSection("attribution", new QIcon().withName("campaign"), Tier.T2,
                List.of("firstTouchUtmSource", "firstTouchUtmMedium", "firstTouchUtmCampaign", "firstTouchUtmContent", "firstTouchUtmTerm", "firstTouchLandingPage", "firstTouchReferrer", "firstTouchDate", "lastTouchUtmSource", "lastTouchUtmMedium", "lastTouchUtmCampaign", "lastTouchUtmContent", "lastTouchUtmTerm", "lastTouchLandingPage", "lastTouchReferrer", "lastTouchDate")).withLabel("Attribution"))
-            .withSection(SectionFactory.defaultT2("description"))
-            .withSection(SectionFactory.defaultT3("lastActivityDate", "lastContactedDate", "createDate", "modifyDate"));
+            .withSection(new QFieldSection("system", "System", new QIcon("settings"), Tier.T3,
+               List.of("id", "lastActivityDate", "lastContactedDate", "createDate", "modifyDate")));
 
-         ///////////////////////////////////////////////////////////////
-         // inject security fields and locks from CrmQBitConfig      //
-         ///////////////////////////////////////////////////////////////
-         CrmQBitConfig config = (CrmQBitConfig) QBitProductionContext.peekQBitConfig();
-         if(config != null)
-         {
-            if(config.getSecurityFields() != null)
-            {
-               t1Section.setFieldNames(new MutableList<>(t1Section.getFieldNames()));
-               for(QFieldMetaData fieldMetaData : config.getSecurityFields())
-               {
-                  table.addField(fieldMetaData.clone());
-                  t1Section.getFieldNames().add(fieldMetaData.getName());
-               }
-            }
 
-            if(config.getRecordSecurityLocks() != null)
-            {
-               for(RecordSecurityLock lock : config.getRecordSecurityLocks())
-               {
-                  table.withRecordSecurityLock(lock);
-               }
-            }
-         }
 
          return (table);
       }
@@ -157,19 +127,19 @@ public class Contact extends QRecordEntity
 
 
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstTouchUtmSource;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstTouchUtmMedium;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstTouchUtmCampaign;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstTouchUtmContent;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstTouchUtmTerm;
 
    @QField(maxLength = 1000, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
@@ -181,19 +151,19 @@ public class Contact extends QRecordEntity
    @QField()
    private Instant firstTouchDate;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastTouchUtmSource;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastTouchUtmMedium;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastTouchUtmCampaign;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastTouchUtmContent;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastTouchUtmTerm;
 
    @QField(maxLength = 1000, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
@@ -208,16 +178,16 @@ public class Contact extends QRecordEntity
    @QField(isEditable = false, isPrimaryKey = true)
    private Integer id;
 
-   @QField(isRequired = true, maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String firstName;
 
-   @QField(isRequired = true, maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String lastName;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 320, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String email;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 320, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String secondaryEmail;
 
    @QField(maxLength = 50, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
@@ -241,7 +211,7 @@ public class Contact extends QRecordEntity
    @QField(possibleValueSourceName = LeadSource.TABLE_NAME)
    private Integer leadSourceId;
 
-   @QField(isRequired = true)
+   @QField()
    private String ownerUserId;
 
    @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)

src/main/java/com/kingsrook/qbits/crm/core/model/Currency.java

@@ -106,7 +106,7 @@ public class Currency extends QRecordEntity
    @QField(isRequired = true, defaultValue = "true")
    private Boolean isActive;
 
-   @QField()
+   @QField(isEditable = false)
    private Instant rateLastUpdatedDate;
 
    @QField(isEditable = false)

src/main/java/com/kingsrook/qbits/crm/core/model/EmailListMember.java

@@ -123,7 +123,7 @@ public class EmailListMember extends QRecordEntity
    @QField(possibleValueSourceName = Contact.TABLE_NAME)
    private Integer contactId;
 
-   @QField(isRequired = true, maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(isRequired = true, maxLength = 320, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String email;
 
    @QField(maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)

src/main/java/com/kingsrook/qbits/crm/core/model/FormSubmission.java

@@ -129,7 +129,7 @@ public class FormSubmission extends QRecordEntity
    @QField(isRequired = true, possibleValueSourceName = CrmFormType.NAME)
    private Integer formType;
 
-   @QField(isRequired = true, maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(isRequired = true, maxLength = 320, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String email;
 
    @QField(maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
@@ -150,19 +150,19 @@ public class FormSubmission extends QRecordEntity
    @QField(maxLength = 1000, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String sourceUrl;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String utmSource;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String utmMedium;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String utmCampaign;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String utmTerm;
 
-   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 500, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String utmContent;
 
    @QField(maxLength = 1000, valueTooLongBehavior = ValueTooLongBehavior.ERROR)

src/main/java/com/kingsrook/qbits/crm/core/model/enums/CrmEmailStatus.java

@@ -40,7 +40,13 @@ public enum CrmEmailStatus implements PossibleValueEnum<Integer>
    DRAFT(1, "Draft"),
    SENT(2, "Sent"),
    DELIVERED(3, "Delivered"),
-   FAILED(4, "Failed");
+   FAILED(4, "Failed"),
+   QUEUED(5, "Queued"),
+   BOUNCED(6, "Bounced"),
+   COMPLAINED(7, "Complained"),
+   OPENED(8, "Opened"),
+   CLICKED(9, "Clicked"),
+   SUPPRESSED(10, "Suppressed");
 
    private final Integer id;
    private final String  label;

src/main/java/com/kingsrook/qbits/crm/core/processes/GdprAnonymizeContactProcess.java

@@ -18,147 +18,30 @@
  * limitations under the License.
  */
 
-
-/*******************************************************************************
- ** GDPR right-to-erasure process. Anonymizes PII on a contact, scrubs audit
- ** log entries, deletes attachments, unenrolls from sequences, creates a
- ** consent-withdrawn record, and logs the anonymization event.
- *******************************************************************************/
-
 package com.kingsrook.qbits.crm.core.processes;
 
 
-import java.time.Instant;
-import com.kingsrook.qbits.crm.core.model.ConsentRecord;
-import com.kingsrook.qbits.crm.core.model.Contact;
-import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
-import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
-import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.privacy.CrmPersonalData;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
-import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
-import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
-import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
-import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
-import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryOutput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
-import com.kingsrook.qqq.backend.core.model.data.QRecord;
 
 
 /*******************************************************************************
- ** Backend operation used by the streamed CRM actions for GDPR anonymization of a contact.
+ ** Backend operation for the streamed Erase Personal Data action.
  *******************************************************************************/
 public class GdprAnonymizeContactProcess implements BackendStep
 {
-   private static final QLogger LOG = QLogger.getLogger(GdprAnonymizeContactProcess.class);
-
    public static final String NAME = "crm_gdpr_anonymize_contact";
 
-   private static final String ANONYMIZED = "[ANONYMIZED]";
 
-
-
-   /*******************************************************************************
-    ** Execute the GDPR anonymization process.
-    *******************************************************************************/
    @Override
    public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
    {
-      Integer contactId     = input.getValueInteger("contactId");
-
-      ///////////////////////////////////////////
-      // Step 1: load and validate contact     //
-      ///////////////////////////////////////////
-      QRecord contactRecord = GetAction.execute(Contact.TABLE_NAME, contactId);
-      if(contactRecord == null)
-      {
-         throw new QException("Contact not found: " + contactId);
-      }
-
-      ///////////////////////////////////////////
-      // Step 2: anonymize PII fields          //
-      ///////////////////////////////////////////
-      QRecord updateRecord = new QRecord()
-         .withValue("id", contactId)
-         .withValue("firstName", ANONYMIZED)
-         .withValue("lastName", ANONYMIZED)
-         .withValue("email", "anonymized-" + contactId + "@removed.invalid")
-         .withValue("phone", null)
-         .withValue("mobilePhone", null)
-         .withValue("secondaryEmail", null)
-         .withValue("addressLine1", null)
-         .withValue("addressLine2", null)
-         .withValue("city", null)
-         .withValue("state", null)
-         .withValue("postalCode", null)
-         .withValue("country", null)
-         .withValue("website", null)
-         .withValue("linkedinUrl", null)
-         .withValue("description", null)
-         .withValue("doNotEmail", true)
-         .withValue("doNotCall", true);
-
-      new UpdateAction().execute(
-         new UpdateInput(Contact.TABLE_NAME).withRecord(updateRecord));
-
-      ///////////////////////////////////////////
-      // Step 3: unenroll from sequences       //
-      ///////////////////////////////////////////
-      unenrollFromSequences(contactId);
-
-      ///////////////////////////////////////////
-      // Step 4: create consent record         //
-      ///////////////////////////////////////////
-      new InsertAction().execute(
-         new InsertInput(ConsentRecord.TABLE_NAME).withRecordEntity(
-            new ConsentRecord()
-               .withContactId(contactId)
-               .withConsentType(CrmConsentType.DATA_PROCESSING.getPossibleValueId())
-               .withStatus(CrmConsentStatus.WITHDRAWN.getPossibleValueId())
-               .withSource("GDPR Anonymization Process")
-               .withConsentDate(Instant.now())));
-
+      Integer contactId = input.getValueInteger("contactId");
+      CrmPersonalData.erase(contactId);
       output.addValue("contactId", contactId);
       output.addValue("anonymized", true);
    }
-
-
-
-   /***************************************************************************
-    ** Unenroll from any active sequence enrollments for this contact.
-    ***************************************************************************/
-   private void unenrollFromSequences(Integer contactId) throws QException
-   {
-      try
-      {
-         QueryOutput enrollments = new QueryAction().execute(
-            new QueryInput("crm_sequence_enrollment")
-               .withFilter(new QQueryFilter()
-                  .withCriteria(new QFilterCriteria("contactId", QCriteriaOperator.EQUALS, contactId))
-                  .withCriteria(new QFilterCriteria("status", QCriteriaOperator.EQUALS, CrmEnrollmentStatus.ACTIVE.getPossibleValueId()))));
-
-         for(QRecord record : enrollments.getRecords())
-         {
-            QRecord updateRecord = new QRecord()
-               .withValue("id", record.getValueInteger("id"))
-               .withValue("status", CrmEnrollmentStatus.UNENROLLED.getPossibleValueId());
-
-            new UpdateAction().execute(
-               new UpdateInput("crm_sequence_enrollment").withRecord(updateRecord));
-         }
-      }
-      catch(Exception e)
-      {
-         LOG.warn("Error unenrolling contact from sequences during GDPR anonymization", e);
-      }
-   }
-
 }

src/main/java/com/kingsrook/qbits/crm/deals/CrmDealNotifications.java

@@ -0,0 +1,108 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.deals;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.scoring.JobState;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.alerts.NotificationAudience;
+import com.kingsrook.qqq.backend.core.alerts.NotificationSignal;
+import com.kingsrook.qqq.backend.core.alerts.QAlerts;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Deal age notifications with a persistent once-per-deal-and-stage checkpoint.
+ *******************************************************************************/
+public final class CrmDealNotifications
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmDealNotifications()
+   {
+   }
+
+   /*******************************************************************************
+    ** Scan open deals in keyset pages, resolving stage metadata once per run.
+    *******************************************************************************/
+   public static void checkRotting() throws QException
+   {
+      Map<Integer, QRecord> stages = new HashMap<>();
+      for(QRecord stage : new QueryAction().execute(new QueryInput("crm_pipeline_stage")).getRecords())
+      {
+         stages.put(stage.getValueInteger("id"), stage);
+      }
+      Integer lastId = null;
+      Instant now = Instant.now();
+      while(true)
+      {
+         QQueryFilter filter = new QQueryFilter().withOrderBy(new QFilterOrderBy("id")).withLimit(200);
+         if(lastId != null)
+         {
+            filter.withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId));
+         }
+         List<QRecord> page = new QueryAction().execute(new QueryInput("crm_deal").withFilter(filter)).getRecords();
+         for(QRecord deal : page)
+         {
+            lastId = deal.getValueInteger("id");
+            QRecord stage = stages.get(deal.getValueInteger("pipelineStageId"));
+            Instant entered = deal.getValueInstant("stageEnteredDate");
+            if(stage == null || entered == null || deal.getValueString("ownerUserId") == null
+               || Boolean.TRUE.equals(stage.getValueBoolean("isClosedWon")) || Boolean.TRUE.equals(stage.getValueBoolean("isClosedLost")))
+            {
+               continue;
+            }
+            Integer days = stage.getValueInteger("rotDays");
+            if(days == null || days <= 0 || !entered.isBefore(now.minus(days, ChronoUnit.DAYS)))
+            {
+               continue;
+            }
+            String key = "deal:" + lastId + ":stage:" + stage.getValue("id");
+            String checkpoint = "crm.deal.rotting:" + key;
+            if(new QueryAction().execute(new QueryInput(JobState.TABLE_NAME)
+               .withFilter(new QQueryFilter(new QFilterCriteria("name", QCriteriaOperator.EQUALS, checkpoint)))).getRecords().isEmpty())
+            {
+               QAlerts.notify(new NotificationSignal("Deal needs attention").withSourceName("crm.deal.rotting").withSourceKey(key)
+                  .withSourceTableName("crm_deal").withSourceRecordId(lastId.toString())
+                  .withAudience(NotificationAudience.user(deal.getValueString("ownerUserId"))));
+               CrmRecords.insert(JobState.TABLE_NAME, new QRecord().withValue("name", checkpoint).withValue("lastSuccess", now));
+            }
+         }
+         if(page.size() < 200)
+         {
+            break;
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/deals/customizers/DealInitializationCustomizer.java

@@ -31,6 +31,7 @@ package com.kingsrook.qbits.crm.deals.customizers;
 import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.time.Instant;
+import java.time.ZoneOffset;
 import java.util.List;
 import com.kingsrook.qbits.crm.CrmSessionUtils;
 import com.kingsrook.qbits.crm.deals.model.Deal;
@@ -130,6 +131,13 @@ public class DealInitializationCustomizer extends AbstractPostInsertCustomizer
          }
       }
 
+      if(stage != null && (Boolean.TRUE.equals(stage.getIsClosedWon()) || Boolean.TRUE.equals(stage.getIsClosedLost()))
+         && record.getValue("actualCloseDate") == null)
+      {
+         updateRecord.setValue("actualCloseDate", now.atZone(ZoneOffset.UTC).toLocalDate());
+         needsUpdate = true;
+      }
+
       ///////////////////////////////////////////
       // calculate weightedAmount              //
       ///////////////////////////////////////////

src/main/java/com/kingsrook/qbits/crm/deals/customizers/DealStageChangeCustomizer.java

@@ -51,6 +51,9 @@ import com.kingsrook.qbits.crm.sync.CrmCurrencyUtils;
 import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreUpdateCustomizer;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.alerts.NotificationAudience;
+import com.kingsrook.qqq.backend.core.alerts.NotificationSignal;
+import com.kingsrook.qqq.backend.core.alerts.QAlerts;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
@@ -192,6 +195,14 @@ public class DealStageChangeCustomizer extends AbstractPreUpdateCustomizer
       // insert DealStageHistory row           //
       ///////////////////////////////////////////
       insertStageHistoryRow(record, oldRecord, oldStageId, newStageId, now);
+      String owner = record.getValues().containsKey("ownerUserId") ? record.getValueString("ownerUserId") : oldRecord.getValueString("ownerUserId");
+      if(Boolean.TRUE.equals(newStage.getIsClosedWon()) && owner != null)
+      {
+         QAlerts.notify(new NotificationSignal("Deal won").withSourceName("crm.deal.won")
+            .withSourceKey("deal:" + record.getValue("id") + ":stage:" + newStageId + ":" + now)
+            .withSourceTableName(Deal.TABLE_NAME).withSourceRecordId(record.getValueString("id"))
+            .withAudience(NotificationAudience.user(owner)), updateInput == null ? null : updateInput.getTransaction());
+      }
    }
 
 

src/main/java/com/kingsrook/qbits/crm/deals/model/Deal.java

@@ -30,7 +30,6 @@ import java.math.BigDecimal;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.util.List;
-import com.kingsrook.qbits.crm.CrmQBitConfig;
 import com.kingsrook.qbits.crm.activities.model.Activity;
 import com.kingsrook.qbits.crm.core.model.Company;
 import com.kingsrook.qbits.crm.core.model.Contact;
@@ -52,13 +51,10 @@ import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.Child
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildRecordListWidget;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.ChildTable;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.annotations.QMetaDataProducingEntity;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.QBitProductionContext;
-import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.SectionFactory;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
-import com.kingsrook.qqq.backend.core.utils.collections.MutableList;
 
 
 /*******************************************************************************
@@ -125,30 +121,7 @@ public class Deal extends QRecordEntity
             .withSection(SectionFactory.defaultT2("description"))
             .withSection(SectionFactory.defaultT3("stageEnteredDate", "lastActivityDate", "createDate", "modifyDate"));
 
-         ///////////////////////////////////////////////////////////////
-         // inject security fields and locks from CrmQBitConfig      //
-         ///////////////////////////////////////////////////////////////
-         CrmQBitConfig config = (CrmQBitConfig) QBitProductionContext.peekQBitConfig();
-         if(config != null)
-         {
-            if(config.getSecurityFields() != null)
-            {
-               t1Section.setFieldNames(new MutableList<>(t1Section.getFieldNames()));
-               for(QFieldMetaData fieldMetaData : config.getSecurityFields())
-               {
-                  table.addField(fieldMetaData.clone());
-                  t1Section.getFieldNames().add(fieldMetaData.getName());
-               }
-            }
 
-            if(config.getRecordSecurityLocks() != null)
-            {
-               for(RecordSecurityLock lock : config.getRecordSecurityLocks())
-               {
-                  table.withRecordSecurityLock(lock);
-               }
-            }
-         }
 
          ///////////////////////////////////////////////////////////
          // Only offer stages belonging to the selected pipeline. //
@@ -156,6 +129,9 @@ public class Deal extends QRecordEntity
          table.getField("pipelineStageId").withPossibleValueSourceFilter(new QQueryFilter(
             new QFilterCriteria("pipelineId", QCriteriaOperator.EQUALS, "${input.pipelineId}")));
 
+         table.getField("primaryContactId").withPossibleValueSourceFilter(new QQueryFilter(
+            new QFilterCriteria("companyId", QCriteriaOperator.EQUALS, "${input.companyId}")));
+
          return (table);
       }
    }
@@ -195,7 +171,7 @@ public class Deal extends QRecordEntity
    @QField(possibleValueSourceName = Contact.TABLE_NAME)
    private Integer primaryContactId;
 
-   @QField(isRequired = true)
+   @QField()
    private String ownerUserId;
 
    @QField(possibleValueSourceName = LeadSource.TABLE_NAME)

src/main/java/com/kingsrook/qbits/crm/email/CrmEmailProcessIdentity.java

@@ -0,0 +1,55 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.email;
+
+
+import com.kingsrook.qqq.backend.core.actions.processes.listeners.ProcessLifecycleListenerInterface;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessOutput;
+
+
+/*******************************************************************************
+ ** Carry the core process UUID across Review/Result and retries in process state.
+ *******************************************************************************/
+public class CrmEmailProcessIdentity implements ProcessLifecycleListenerInterface
+{
+   @Override
+   public boolean appliesTo(String processName)
+   {
+      return ("crm_send_email".equals(processName));
+   }
+
+   @Override
+   public void onProcessStarted(RunProcessInput input)
+   {
+      input.getProcessState().getValues().put("crmEmailProcessUUID", input.getProcessUUID());
+   }
+
+   @Override
+   public void onProcessCompleted(RunProcessInput input, RunProcessOutput output)
+   {
+   }
+
+   @Override
+   public void onProcessFailed(RunProcessInput input, Exception exception)
+   {
+   }
+}

src/main/java/com/kingsrook/qbits/crm/email/CrmEmailTransport.java

@@ -21,8 +21,11 @@
 package com.kingsrook.qbits.crm.email;
 
 
+import java.time.Instant;
+import java.util.Optional;
 import com.kingsrook.qbits.crm.CrmQBitConfig;
 import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEmailStatus;
 import com.kingsrook.qbits.email.api.EmailApi;
 import com.kingsrook.qbits.email.api.EmailApiCategory;
 import com.kingsrook.qbits.email.api.EmailApiEffectOutcome;
@@ -87,6 +90,14 @@ public class CrmEmailTransport
     ** Deliver one message, using a stable CRM purpose/id key for the durable email outbox.
     *******************************************************************************/
    public void send(String purpose, String id, Integer contactId, String address, String subject, String body, boolean marketing) throws QException
+   {
+      deliver(purpose, id, contactId, address, subject, body, marketing);
+   }
+
+   /*******************************************************************************
+    ** Return the transport result without guessing that queued email was sent.
+    *******************************************************************************/
+   private Delivery deliver(String purpose, String id, Integer contactId, String address, String subject, String body, boolean marketing) throws QException
    {
       if(emailInstalled())
       {
@@ -98,7 +109,9 @@ public class CrmEmailTransport
          {
             throw (new QUserFacingException("The email service could not accept this message."));
          }
-         return;
+         var message = result.message();
+         return (message == null ? new Delivery(null, CrmEmailStatus.QUEUED, null, null, null, null, null)
+            : new Delivery(String.valueOf(message.id()), status(message.status()), message.sentDate(), message.deliveredDate(), null, null, null));
       }
       if(readiness() != CrmReadiness.CORE_MESSAGING)
       {
@@ -107,5 +120,52 @@ public class CrmEmailTransport
       new SendMessageAction().execute(new SendMessageInput().withMessagingProviderName(config.getMessagingProviderName())
          .withTo(new Party().withAddress(address).withRole(EmailPartyRole.TO)).withSubject(subject)
          .withContent(new Content().withBody(body).withContentRole(EmailContentRole.TEXT)));
+      return (new Delivery(null, CrmEmailStatus.SENT, Instant.now(), null, null, null, null));
+   }
+
+   /*******************************************************************************
+    ** CRM-owned delivery snapshot; optional email types never escape this adapter.
+    *******************************************************************************/
+   public record Delivery(String messageId, CrmEmailStatus status, Instant sentDate, Instant deliveredDate,
+                          Instant openedDate, Instant clickedDate, Instant bouncedDate)
+   {
+   }
+
+   /*******************************************************************************
+    ** Send and return the actual outbox state, or the successful core send state.
+    *******************************************************************************/
+   public Delivery sendMessage(String purpose, String id, Integer contactId, String address, String subject, String body, boolean marketing) throws QException
+   {
+      send(purpose, id, contactId, address, subject, body, marketing);
+      return (lookup("crm:" + purpose + ":" + id).orElseGet(() ->
+         new Delivery(null, CrmEmailStatus.SENT, Instant.now(), null, null, null, null)));
+   }
+
+   /*******************************************************************************
+    ** Read delivery through the published API only. RC.3 exposes sent/delivered dates.
+    *******************************************************************************/
+   public Optional<Delivery> lookup(String key) throws QException
+   {
+      if(!emailInstalled() || key == null)
+      {
+         return (Optional.empty());
+      }
+      return (EmailApi.getMessageByIdempotencyKey(key).map(message -> new Delivery(String.valueOf(message.id()),
+         status(message.status()), message.sentDate(), message.deliveredDate(), null, null, null)));
+   }
+
+   /*******************************************************************************
+    ** Preserve known delivery states and leave unknown/pending states eligible for sync.
+    *******************************************************************************/
+   private CrmEmailStatus status(String status)
+   {
+      try
+      {
+         return (CrmEmailStatus.valueOf(status));
+      }
+      catch(IllegalArgumentException | NullPointerException e)
+      {
+         return (CrmEmailStatus.QUEUED);
+      }
    }
 }

src/main/java/com/kingsrook/qbits/crm/email/CrmEmails.java

@@ -0,0 +1,167 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.email;
+
+
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.crm.api.ActivityKind;
+import com.kingsrook.qbits.crm.api.CrmMarketingApi;
+import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.core.model.enums.CrmDirection;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QUserFacingException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Shared CRM template rendering, transport delivery and timeline recording.
+ *******************************************************************************/
+public final class CrmEmails
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmEmails()
+   {
+   }
+
+   /*******************************************************************************
+    ** A skip reason suitable for standard WARNING summary lines.
+    *******************************************************************************/
+   public static String skipReason(QRecord contact, CrmEmailTransport transport) throws QException
+   {
+      if(Boolean.TRUE.equals(contact.getValueBoolean("doNotEmail")))
+      {
+         return ("Contact has opted out of email");
+      }
+      if(contact.getValueString("email") == null || contact.getValueString("email").isBlank())
+      {
+         return ("Contact has no email address");
+      }
+      return (transport.readiness() == CrmReadiness.NOT_CONFIGURED ? "CRM email is not configured" : null);
+   }
+
+   /*******************************************************************************
+    ** Send once using the caller's stable purpose/id and record the transport outcome.
+    *******************************************************************************/
+   public static void send(CrmEmailTransport transport, QRecord contact, Integer templateId, String subject, String body,
+                           String purpose, String id, Integer enrollmentId) throws QException
+   {
+      String key = "crm:" + purpose + ":" + id;
+      List<QRecord> existing = new QueryAction().execute(new QueryInput("crm_email_message").withFilter(
+         new QQueryFilter(new QFilterCriteria("idempotencyKey", QCriteriaOperator.EQUALS, key)))).getRecords();
+      if(!existing.isEmpty())
+      {
+         recordActivity(existing.getFirst());
+         return;
+      }
+      if(templateId != null)
+      {
+         QRecord template = GetAction.execute("crm_email_template", templateId);
+         if(template == null)
+         {
+            throw (new QUserFacingException("Email template is unavailable"));
+         }
+         subject = subject == null || subject.isBlank() ? template.getValueString("subject") : subject;
+         body = body == null || body.isBlank() ? template.getValueString("bodyText") : body;
+         if(body == null)
+         {
+            body = template.getValueString("bodyHtml");
+         }
+      }
+      if(subject == null || subject.isBlank() || body == null || body.isBlank())
+      {
+         throw (new QUserFacingException("Email subject and body are required"));
+      }
+      subject = render(subject, contact);
+      body = render(body, contact);
+      CrmEmailTransport.Delivery delivery = transport.sendMessage(purpose, id, contact.getValueInteger("id"),
+         contact.getValueString("email"), subject, body, enrollmentId != null);
+      QRecord message = CrmRecords.insert("crm_email_message", new QRecord().withValue("contactId", contact.getValue("id"))
+         .withValue("emailTemplateId", templateId).withValue("sequenceEnrollmentId", enrollmentId)
+         .withValue("toAddresses", contact.getValue("email")).withValue("subject", subject)
+         .withValue("direction", CrmDirection.OUTBOUND.getId()).withValue("status", delivery.status().getId())
+         .withValue("idempotencyKey", key).withValue("emailMessageId", delivery.messageId())
+         .withValue("sentDate", delivery.sentDate()).withValue("deliveredDate", delivery.deliveredDate()));
+      recordActivity(message);
+   }
+
+   /*******************************************************************************
+    ** Repair a partially recorded send without sending again or duplicating its activity.
+    *******************************************************************************/
+   private static void recordActivity(QRecord message) throws QException
+   {
+      if(message.getValue("activityId") != null)
+      {
+         return;
+      }
+      String description = "Email: " + message.getValueString("idempotencyKey");
+      QQueryFilter filter = new QQueryFilter(new QFilterCriteria("contactId", QCriteriaOperator.EQUALS, message.getValue("contactId")),
+         new QFilterCriteria("description", QCriteriaOperator.EQUALS, description));
+      List<QRecord> activities = new QueryAction().execute(new QueryInput("crm_activity").withFilter(filter)).getRecords();
+      if(activities.isEmpty())
+      {
+         new CrmMarketingApi().recordActivity(message.getValueInteger("contactId"),
+            message.getValue("sequenceEnrollmentId") == null ? ActivityKind.EMAIL : ActivityKind.SEQUENCE_STEP,
+            message.getValueString("subject"), description);
+         activities = new QueryAction().execute(new QueryInput("crm_activity").withFilter(filter)).getRecords();
+      }
+      CrmRecords.update("crm_email_message", new QRecord().withValue("id", message.getValue("id"))
+         .withValue("activityId", activities.getFirst().getValue("id")));
+   }
+
+   /*******************************************************************************
+    ** Literal replacements avoid treating customer data as a template program.
+    *******************************************************************************/
+   public static String render(String text, QRecord contact) throws QException
+   {
+      QRecord company = contact.getValue("companyId") == null ? null : GetAction.execute("crm_company", contact.getValue("companyId"));
+      Map<String, String> fields = Map.of("contact.firstName", value(contact, "firstName"), "contact.lastName", value(contact, "lastName"),
+         "company.name", value(company, "name"), "owner.name", value(contact, "ownerUserId"));
+      // Replace each token in the original text only, so inserted values cannot introduce merge fields.
+      java.util.regex.Matcher matcher = java.util.regex.Pattern.compile("\\{\\{(contact.firstName|contact.lastName|company.name|owner.name|unsubscribeUrl)\\}\\}").matcher(text);
+      StringBuilder rendered = new StringBuilder();
+      while(matcher.find())
+      {
+         String replacement = "unsubscribeUrl".equals(matcher.group(1))
+            ? new CrmMarketingApi().buildUnsubscribeUrl(contact.getValueInteger("id"), null) : fields.get(matcher.group(1));
+         matcher.appendReplacement(rendered, java.util.regex.Matcher.quoteReplacement(replacement));
+      }
+      matcher.appendTail(rendered);
+      return (rendered.toString());
+   }
+
+   /*******************************************************************************
+    ** Missing merge values render as empty strings.
+    *******************************************************************************/
+   private static String value(QRecord row, String field)
+   {
+      return (row == null || row.getValueString(field) == null ? "" : row.getValueString(field));
+   }
+}

src/main/java/com/kingsrook/qbits/crm/email/model/EmailMessage.java

@@ -46,6 +46,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.SectionFactory;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
 
 
 /*******************************************************************************
@@ -75,6 +76,7 @@ public class EmailMessage extends QRecordEntity
       public QTableMetaData customizeMetaData(QInstance qInstance, QTableMetaData table) throws QException
       {
          table
+            .withUniqueKey(new UniqueKey("idempotencyKey"))
             .withIcon(new QIcon().withName("email"))
             .withRecordLabelFormat("%s")
             .withRecordLabelFields("subject")
@@ -85,10 +87,10 @@ public class EmailMessage extends QRecordEntity
                List.of("bodyHtml", "bodyText")))
             .withSection(new QFieldSection("tracking", new QIcon("visibility"), Tier.T2,
                List.of("isTracked", "openCount", "clickCount", "firstOpenedDate", "firstClickedDate",
-                  "bounceType", "isSpamComplaint")))
+                  "bounceType", "isSpamComplaint", "deliveredDate", "bouncedDate")))
             .withSection(new QFieldSection("references", new QIcon("link"), Tier.T2,
                List.of("contactId", "activityId", "emailTemplateId", "sequenceEnrollmentId",
-                  "threadId", "replyToEmailId")))
+                  "threadId", "replyToEmailId", "idempotencyKey", "emailMessageId")))
             .withSection(SectionFactory.defaultT3("createDate", "modifyDate"));
 
          return (table);
@@ -106,7 +108,7 @@ public class EmailMessage extends QRecordEntity
    @QField(possibleValueSourceName = Contact.TABLE_NAME)
    private Integer contactId;
 
-   @QField(isRequired = true, maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
+   @QField(maxLength = 250, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
    private String fromAddress;
 
    @QField(maxLength = 100, valueTooLongBehavior = ValueTooLongBehavior.ERROR)
@@ -172,6 +174,18 @@ public class EmailMessage extends QRecordEntity
    @QField()
    private Integer replyToEmailId;
 
+   @QField(maxLength = 250)
+   private String idempotencyKey;
+
+   @QField(maxLength = 100)
+   private String emailMessageId;
+
+   @QField()
+   private Instant deliveredDate;
+
+   @QField()
+   private Instant bouncedDate;
+
    @QField(isEditable = false)
    private Instant createDate;
 
@@ -1031,4 +1045,103 @@ public class EmailMessage extends QRecordEntity
       return (this);
    }
 
+   /*******************************************************************************
+    ** Get idempotencyKey.
+    *******************************************************************************/
+   public String getIdempotencyKey()
+   {
+      return (idempotencyKey);
+   }
+
+   /*******************************************************************************
+    ** Set idempotencyKey.
+    *******************************************************************************/
+   public EmailMessage withIdempotencyKey(String idempotencyKey)
+   {
+      this.idempotencyKey = idempotencyKey;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Get emailMessageId.
+    *******************************************************************************/
+   public String getEmailMessageId()
+   {
+      return (emailMessageId);
+   }
+
+   /*******************************************************************************
+    ** Set emailMessageId.
+    *******************************************************************************/
+   public EmailMessage withEmailMessageId(String emailMessageId)
+   {
+      this.emailMessageId = emailMessageId;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Get deliveredDate.
+    *******************************************************************************/
+   public Instant getDeliveredDate()
+   {
+      return (deliveredDate);
+   }
+
+   /*******************************************************************************
+    ** Set deliveredDate.
+    *******************************************************************************/
+   public EmailMessage withDeliveredDate(Instant deliveredDate)
+   {
+      this.deliveredDate = deliveredDate;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Get bouncedDate.
+    *******************************************************************************/
+   public Instant getBouncedDate()
+   {
+      return (bouncedDate);
+   }
+
+   /*******************************************************************************
+    ** Set bouncedDate.
+    *******************************************************************************/
+   public EmailMessage withBouncedDate(Instant bouncedDate)
+   {
+      this.bouncedDate = bouncedDate;
+      return (this);
+   }
+
+   /*******************************************************************************
+    ** Set idempotencyKey for entity mapping.
+    *******************************************************************************/
+   public void setIdempotencyKey(String idempotencyKey)
+   {
+      this.idempotencyKey = idempotencyKey;
+   }
+
+   /*******************************************************************************
+    ** Set emailMessageId for entity mapping.
+    *******************************************************************************/
+   public void setEmailMessageId(String emailMessageId)
+   {
+      this.emailMessageId = emailMessageId;
+   }
+
+   /*******************************************************************************
+    ** Set deliveredDate for entity mapping.
+    *******************************************************************************/
+   public void setDeliveredDate(Instant deliveredDate)
+   {
+      this.deliveredDate = deliveredDate;
+   }
+
+   /*******************************************************************************
+    ** Set bouncedDate for entity mapping.
+    *******************************************************************************/
+   public void setBouncedDate(Instant bouncedDate)
+   {
+      this.bouncedDate = bouncedDate;
+   }
 }

src/main/java/com/kingsrook/qbits/crm/email/processes/ExpireConsentsProcess.java

@@ -0,0 +1,104 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.email.processes;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.List;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.core.model.enums.CrmListMemberStatus;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.actions.tables.CountAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.count.CountInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+
+
+/*******************************************************************************
+ ** Scheduled CRM maintenance: crm_expire_consents.
+ *******************************************************************************/
+public class ExpireConsentsProcess implements BackendStep, MetaDataProducerInterface<QProcessMetaData>
+{
+   public static final String NAME = "crm_expire_consents";
+
+   @Override
+   public QProcessMetaData produce(QInstance instance)
+   {
+      return (new QProcessMetaData().withName(NAME).withLabel("ExpireConsents").withIsHidden(true)
+         .withStep(new QBackendStepMetaData().withName("execute").withCode(new QCodeReference(ExpireConsentsProcess.class))));
+   }
+
+   @Override
+   public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+   {
+      Instant now = Instant.now();
+      Instant cutoff = now.minus(14, ChronoUnit.DAYS);
+      Integer lastId = null;
+      int expired = 0;
+      while(true)
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("status", QCriteriaOperator.EQUALS, CrmListMemberStatus.PENDING_CONFIRMATION.getId()))
+            .withOrderBy(new QFilterOrderBy("id")).withLimit(200);
+         if(lastId != null)
+         {
+            filter.addCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId));
+         }
+         List<QRecord> page = new QueryAction().execute(new QueryInput("crm_email_list_member").withFilter(filter)).getRecords();
+         for(QRecord member : page)
+         {
+            lastId = member.getValueInteger("id");
+            Instant pendingSince = member.getValueInstant("confirmationSentDate");
+            if(pendingSince == null)
+            {
+               pendingSince = member.getValueInstant("createDate");
+            }
+            if(pendingSince != null && !pendingSince.isAfter(cutoff))
+            {
+               CrmRecords.update("crm_email_list_member", new QRecord().withValue("id", lastId)
+                  .withValue("status", CrmListMemberStatus.UNSUBSCRIBED.getId()).withValue("confirmationTokenHash", null)
+                  .withValue("unsubscribedDate", now));
+               expired++;
+            }
+         }
+         if(page.size() < 200)
+         {
+            break;
+         }
+      }
+      output.addValue("expiredPendingCount", expired);
+      output.addValue("expiredConsentCount", new CountAction().execute(new CountInput("crm_consent_record")
+         .withFilter(new QQueryFilter(new QFilterCriteria("expiryDate", QCriteriaOperator.LESS_THAN_OR_EQUALS, now)))).getCount());
+   }
+}

src/main/java/com/kingsrook/qbits/crm/email/processes/ProcessSequenceStepsProcess.java

@@ -34,9 +34,15 @@ import java.time.temporal.ChronoUnit;
 import java.util.List;
 import com.kingsrook.qbits.crm.activities.model.Activity;
 import com.kingsrook.qbits.crm.activities.model.ActivityType;
+import com.kingsrook.qbits.crm.api.CrmApi;
+import com.kingsrook.qbits.crm.api.CrmMarketingApi;
+import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.core.CrmRecords;
 import com.kingsrook.qbits.crm.core.model.Contact;
 import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
 import com.kingsrook.qbits.crm.core.model.enums.CrmSequenceStepType;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.email.CrmEmails;
 import com.kingsrook.qbits.crm.email.model.EmailSequence;
 import com.kingsrook.qbits.crm.email.model.SequenceEnrollment;
 import com.kingsrook.qbits.crm.email.model.SequenceStep;
@@ -45,6 +51,8 @@ import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.alerts.AlertSignal;
+import com.kingsrook.qqq.backend.core.alerts.QAlerts;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
@@ -79,6 +87,15 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
 
    private static final int MAX_FAILURES = 3;
 
+   /*******************************************************************************
+    ** Resolve the host transport; tests may supply a fake.
+    *******************************************************************************/
+   protected CrmEmailTransport emailTransport() throws QException
+   {
+      return (new CrmEmailTransport(CrmApi.config()));
+   }
+
+
 
 
    /*******************************************************************************
@@ -92,7 +109,6 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
          .withIsHidden(true)
          .withLabel("Process Sequence Steps")
          .withIcon(new QIcon().withName("play_circle"))
-         // Scheduling is configured by the host application via ScheduledJob records
          .withStepList(List.of(
             new QBackendStepMetaData()
                .withName("execute")
@@ -111,6 +127,18 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
       ///////////////////////////////////////////////////////////
       // query enrollments where status=ACTIVE and due now     //
       ///////////////////////////////////////////////////////////
+      CrmEmailTransport transport = emailTransport();
+      boolean ready = transport.readiness() != CrmReadiness.NOT_CONFIGURED;
+      boolean activeSequences = !new QueryAction().execute(new QueryInput(EmailSequence.TABLE_NAME)
+         .withFilter(new QQueryFilter(new QFilterCriteria("isActive", QCriteriaOperator.EQUALS, true)).withLimit(1))).getRecords().isEmpty();
+      if(!ready && activeSequences)
+      {
+         QAlerts.raise(new AlertSignal("crm.email.unavailable").withDedupKey("transport").withTitle("CRM email is unavailable"));
+      }
+      else if(ready)
+      {
+         QAlerts.resolve("crm.email.unavailable", "transport", "Email transport is ready");
+      }
       int processedCount = 0;
       Integer lastId = null;
       Instant dueThrough = Instant.now();
@@ -130,7 +158,7 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
             SequenceEnrollment enrollment = new SequenceEnrollment(enrollmentRecord);
             try
             {
-               processEnrollment(enrollment);
+               processEnrollment(enrollment, transport);
                processedCount++;
             }
             catch(Exception e)
@@ -154,7 +182,7 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
     ** Process a single enrollment: load the next step and execute it.
     ** Respects businessDaysOnly and sendWindow settings on the sequence.
     ***************************************************************************/
-   private void processEnrollment(SequenceEnrollment enrollment) throws QException
+   private void processEnrollment(SequenceEnrollment enrollment, CrmEmailTransport transport) throws QException
    {
       Integer nextStepNumber = enrollment.getCurrentStepNumber() + 1;
 
@@ -167,6 +195,11 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
       EmailSequence sequence = sequenceGet.getRecord() != null
          ? new EmailSequence(sequenceGet.getRecord()) : null;
 
+      if(sequence == null || !Boolean.TRUE.equals(sequence.getIsActive()))
+      {
+         return;
+      }
+
       /////////////////////////////////////////////
       // load the contact for timezone           //
       /////////////////////////////////////////////
@@ -237,7 +270,27 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
       {
          switch(stepType)
          {
-            case EMAIL -> executeEmailStep(enrollment, step);
+            case EMAIL ->
+            {
+               var eligibility = new CrmMarketingApi().checkEmailEligibility(enrollment.getContactId());
+               if(!eligibility.eligible())
+               {
+                  CrmRecords.update(SequenceEnrollment.TABLE_NAME, new QRecord().withValue("id", enrollment.getId())
+                     .withValue("status", CrmEnrollmentStatus.PAUSED.getId()).withValue("lastFailureMessage", eligibility.reason())
+                     .withValue("nextStepDate", null));
+                  return;
+               }
+               if(transport.readiness() == CrmReadiness.NOT_CONFIGURED)
+               {
+                  return;
+               }
+               if(step.getEmailTemplateId() == null)
+               {
+                  throw (new QException("Sequence email template is required"));
+               }
+               CrmEmails.send(transport, contactGet.getRecord(), step.getEmailTemplateId(), null, null,
+                  "seq", enrollment.getId() + ":" + step.getId(), enrollment.getId());
+            }
             case CALL -> executeCallStep(enrollment, step);
             case TASK -> executeTaskStep(enrollment, step);
             case WAIT ->
@@ -257,50 +310,6 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
 
 
 
-   /***************************************************************************
-    ** Execute an EMAIL step: verify doNotEmail, create an activity record.
-    ***************************************************************************/
-   private void executeEmailStep(SequenceEnrollment enrollment, SequenceStep step) throws QException
-   {
-      ///////////////////////////////////////////////
-      // check doNotEmail                          //
-      ///////////////////////////////////////////////
-      GetOutput contactGet = new GetAction().execute(
-         new GetInput(Contact.TABLE_NAME).withPrimaryKey(enrollment.getContactId()));
-
-      if(contactGet.getRecord() != null)
-      {
-         Contact contact = new Contact(contactGet.getRecord());
-         if(Boolean.TRUE.equals(contact.getDoNotEmail()))
-         {
-            throw (new QException("Contact has opted out of email"));
-         }
-      }
-
-      ///////////////////////////////////////////////
-      // create activity for the email             //
-      ///////////////////////////////////////////////
-      String subject = "Sequence email: step " + step.getStepNumber();
-      if(step.getEmailTemplateId() != null)
-      {
-         subject += " (template #" + step.getEmailTemplateId() + ")";
-      }
-
-      Integer activityTypeId = lookupActivityTypeByName("Email");
-
-      new InsertAction().execute(
-         new InsertInput(Activity.TABLE_NAME).withRecordEntity(
-            new Activity()
-               .withActivityTypeId(activityTypeId)
-               .withContactId(enrollment.getContactId())
-               .withDealId(enrollment.getDealId())
-               .withSubject(subject)
-               .withOwnerUserId("system")
-               .withIsCompleted(true)));
-   }
-
-
-
    /***************************************************************************
     ** Execute a CALL step: create a task activity assigned to the contact owner.
     ***************************************************************************/
@@ -524,6 +533,8 @@ public class ProcessSequenceStepsProcess implements BackendStep, MetaDataProduce
       {
          updateRecord.withValue("status", CrmEnrollmentStatus.FAILED.getPossibleValueId());
          updateRecord.withValue("nextStepDate", null);
+         QAlerts.raise(new AlertSignal("crm.sequence.failing").withDedupKey("enrollment:" + enrollment.getId())
+            .withTitle("Sequence enrollment failed three times"));
       }
 
       new UpdateAction().execute(

src/main/java/com/kingsrook/qbits/crm/email/processes/SyncEmailDeliveryProcess.java

@@ -0,0 +1,153 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.email.processes;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.List;
+import com.kingsrook.qbits.crm.api.CrmApi;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEmailStatus;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QBackendStepMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData;
+
+
+/*******************************************************************************
+ ** Scheduled CRM maintenance: crm_sync_email_delivery.
+ *******************************************************************************/
+public class SyncEmailDeliveryProcess implements BackendStep, MetaDataProducerInterface<QProcessMetaData>
+{
+   public static final String NAME = "crm_sync_email_delivery";
+
+   @Override
+   public QProcessMetaData produce(QInstance instance)
+   {
+      return (new QProcessMetaData().withName(NAME).withLabel("SyncEmailDelivery").withIsHidden(true)
+         .withStep(new QBackendStepMetaData().withName("execute").withCode(new QCodeReference(SyncEmailDeliveryProcess.class))));
+   }
+
+   /*******************************************************************************
+    ** Resolve the host transport; an absent qbit-email yields empty lookups.
+    *******************************************************************************/
+   protected CrmEmailTransport emailTransport() throws QException
+   {
+      return (new CrmEmailTransport(CrmApi.config()));
+   }
+
+   @Override
+   public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
+   {
+      CrmEmailTransport transport = emailTransport();
+      Integer lastId = null;
+      int updated = 0;
+      Instant since = Instant.now().minus(30, ChronoUnit.DAYS);
+      while(true)
+      {
+         QQueryFilter filter = new QQueryFilter(new QFilterCriteria("createDate", QCriteriaOperator.GREATER_THAN_OR_EQUALS, since))
+            .withOrderBy(new QFilterOrderBy("id")).withLimit(200);
+         if(lastId != null)
+         {
+            filter.addCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId));
+         }
+         List<QRecord> page = new QueryAction().execute(new QueryInput("crm_email_message").withFilter(filter)).getRecords();
+         for(QRecord message : page)
+         {
+            lastId = message.getValueInteger("id");
+            if(message.getValueInteger("status") != null && List.of(CrmEmailStatus.BOUNCED.getId(), CrmEmailStatus.COMPLAINED.getId(), CrmEmailStatus.FAILED.getId(),
+               CrmEmailStatus.SUPPRESSED.getId()).contains(message.getValueInteger("status")))
+            {
+               continue;
+            }
+            var delivery = transport.lookup(message.getValueString("idempotencyKey"));
+            if(delivery.isEmpty())
+            {
+               continue;
+            }
+            CrmEmailTransport.Delivery state = delivery.get();
+            QRecord change = new QRecord().withValue("id", lastId).withValue("status", state.status().getId());
+            date(change, "sentDate", state.sentDate());
+            date(change, "deliveredDate", state.deliveredDate());
+            date(change, "firstOpenedDate", state.openedDate());
+            date(change, "firstClickedDate", state.clickedDate());
+            date(change, "bouncedDate", state.bouncedDate());
+            boolean complaint = state.status() == CrmEmailStatus.COMPLAINED;
+            if(complaint || state.status() == CrmEmailStatus.BOUNCED)
+            {
+               Integer contactId = message.getValueInteger("contactId");
+               if(contactId != null)
+               {
+                  CrmRecords.update("crm_contact", new QRecord().withValue("id", contactId).withValue("doNotEmail", true));
+                  String source = complaint ? "Complaint" : "Hard bounce";
+                  // The terminal message checkpoint is written last. A retry must not duplicate consent evidence.
+                  String evidence = "Email: " + message.getValueString("idempotencyKey");
+                  List<QRecord> recorded = new QueryAction().execute(new QueryInput("crm_consent_record").withFilter(new QQueryFilter(
+                     new QFilterCriteria("contactId", QCriteriaOperator.EQUALS, contactId),
+                     new QFilterCriteria("source", QCriteriaOperator.EQUALS, source),
+                     new QFilterCriteria("consentText", QCriteriaOperator.EQUALS, evidence)))).getRecords();
+                  if(recorded.isEmpty())
+                  {
+                     CrmRecords.insert("crm_consent_record", new QRecord().withValue("contactId", contactId)
+                        .withValue("consentType", CrmConsentType.EMAIL.getId()).withValue("status", CrmConsentStatus.WITHDRAWN.getId())
+                        .withValue("consentDate", Instant.now()).withValue("source", source).withValue("consentText", evidence));
+                  }
+               }
+               change.withValue("isSpamComplaint", complaint);
+            }
+            CrmRecords.update("crm_email_message", change);
+            updated++;
+         }
+         if(page.size() < 200)
+         {
+            break;
+         }
+      }
+      output.addValue("updatedCount", updated);
+   }
+
+   /*******************************************************************************
+    ** Never clear a timestamp when the provider has not exposed it.
+    *******************************************************************************/
+   private void date(QRecord row, String field, Instant value)
+   {
+      if(value != null)
+      {
+         row.setValue(field, value);
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/health/CrmHealthChecks.java

@@ -0,0 +1,227 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.health;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.crm.CrmQBitConfig;
+import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.scoring.JobState;
+import com.kingsrook.qbits.crm.scoring.processes.CalculateLeadScoresProcess;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.alerts.AlertSeverity;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.health.HealthCategory;
+import com.kingsrook.qqq.backend.core.health.HealthCheck;
+import com.kingsrook.qqq.backend.core.health.HealthCheckInput;
+import com.kingsrook.qqq.backend.core.health.HealthCheckKind;
+import com.kingsrook.qqq.backend.core.health.HealthCheckMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthCheckOutcome;
+import com.kingsrook.qqq.backend.core.health.HealthChecksMetaData;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+
+
+/*******************************************************************************
+ ** CRM checks registered with the core health registry (HealthChecksMetaData).
+ ** The core HealthRunner schedules them and runs each one in its own automated
+ ** system-user context; no check returns personal values.
+ *******************************************************************************/
+public class CrmHealthChecks
+{
+   public static final String EMAIL        = "crm.email";
+   public static final String SEQUENCE_LAG = "crm.sequence_lag";
+   public static final String LEAD_SCORE   = "crm.lead_score";
+
+   private static final String COMPONENT = "crm";
+
+   private final CrmEmailTransport transport;
+
+
+
+   /*******************************************************************************
+    ** Use the same readiness decision as actual email delivery.
+    *******************************************************************************/
+   public CrmHealthChecks(CrmQBitConfig config)
+   {
+      this(new CrmEmailTransport(config));
+   }
+
+
+
+   /*******************************************************************************
+    ** Allow a host transport adapter.
+    *******************************************************************************/
+   public CrmHealthChecks(CrmEmailTransport transport)
+   {
+      this.transport = transport;
+   }
+
+
+
+   /*******************************************************************************
+    ** Register the CRM checks with the instance's core health registry.
+    ** Production may run repeatedly; an already registered name is kept.
+    *******************************************************************************/
+   public static void register(QInstance instance, CrmQBitConfig config)
+   {
+      new CrmHealthChecks(config).registerWith(instance);
+   }
+
+
+
+   /*******************************************************************************
+    ** Register these checks (with this transport) with the core health registry.
+    *******************************************************************************/
+   public void registerWith(QInstance instance)
+   {
+      HealthChecksMetaData registry = HealthChecksMetaData.ofOrWithNew(instance);
+      add(registry, EMAIL, "CRM email transport", HealthCategory.EMAIL, 300);
+      add(registry, SEQUENCE_LAG, "CRM sequence lag", HealthCategory.JOBS, 300);
+      add(registry, LEAD_SCORE, "CRM lead scoring", HealthCategory.JOBS, 900);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run all checks once in the caller's context, without registering anything.
+    *******************************************************************************/
+   public Map<String, HealthCheckOutcome> run() throws QException
+   {
+      Map<String, HealthCheckOutcome> outcomes = new LinkedHashMap<>();
+      for(String name : List.of(EMAIL, SEQUENCE_LAG, LEAD_SCORE))
+      {
+         outcomes.put(name, check(name).run(new HealthCheckInput()));
+      }
+      return (outcomes);
+   }
+
+
+
+   /*******************************************************************************
+    ** The core SPI body for one named check. Failures are reported as UNKNOWN
+    ** with a fixed message, so no exception text (or value) leaves the check.
+    *******************************************************************************/
+   public HealthCheck check(String name)
+   {
+      return (new HealthCheck()
+      {
+         /*******************************************************************
+          ** Evaluate the named check in the current QContext.
+          *******************************************************************/
+         @Override
+         public HealthCheckOutcome run(HealthCheckInput input)
+         {
+            try
+            {
+               return (switch(name)
+               {
+                  case EMAIL -> email();
+                  case SEQUENCE_LAG -> sequenceLag();
+                  case LEAD_SCORE -> leadScore();
+                  default -> throw (new IllegalArgumentException("Unknown CRM health check"));
+               });
+            }
+            catch(QException | RuntimeException e)
+            {
+               return (HealthCheckOutcome.unknown("CRM check could not be completed"));
+            }
+         }
+      });
+   }
+
+
+
+   /*******************************************************************************
+    ** Add one check definition unless the name is already registered.
+    *******************************************************************************/
+   private void add(HealthChecksMetaData registry, String name, String label, HealthCategory category, int intervalSeconds)
+   {
+      if(registry.getChecks().stream().anyMatch(existing -> name.equals(existing.getName())))
+      {
+         return;
+      }
+      registry.withCheck(new HealthCheckMetaData()
+         .withName(name)
+         .withLabel(label)
+         .withComponent(COMPONENT)
+         .withCategory(category)
+         .withKind(HealthCheckKind.DEPENDENCY)
+         .withSeverity(AlertSeverity.WARNING)
+         .withIntervalSeconds(intervalSeconds)
+         .withTimeoutMs(5000)
+         .withCheckInstance(check(name)));
+   }
+
+
+
+   /*******************************************************************************
+    ** An unconfigured transport is degraded, not a claim that email can be sent.
+    *******************************************************************************/
+   private HealthCheckOutcome email() throws QException
+   {
+      return (transport.readiness() == CrmReadiness.NOT_CONFIGURED
+         ? HealthCheckOutcome.degraded("Email transport not configured")
+         : HealthCheckOutcome.up("Email transport ready"));
+   }
+
+
+
+   /*******************************************************************************
+    ** Query just the oldest active due enrollment.
+    *******************************************************************************/
+   private HealthCheckOutcome sequenceLag() throws QException
+   {
+      List<QRecord> rows = new QueryAction().execute(new QueryInput("crm_sequence_enrollment").withFilter(new QQueryFilter()
+         .withCriteria(new QFilterCriteria("status", QCriteriaOperator.EQUALS, CrmEnrollmentStatus.ACTIVE.getId()))
+         .withCriteria(new QFilterCriteria("nextStepDate", QCriteriaOperator.LESS_THAN, Instant.now().minus(30, ChronoUnit.MINUTES)))
+         .withOrderBy(new QFilterOrderBy("nextStepDate")).withLimit(1))).getRecords();
+      return (rows.isEmpty()
+         ? HealthCheckOutcome.up("No sequence step is more than 30 minutes late")
+         : HealthCheckOutcome.degraded("A sequence step is more than 30 minutes late"));
+   }
+
+
+
+   /*******************************************************************************
+    ** No successful score pass, or one more than three hours old, needs attention.
+    *******************************************************************************/
+   private HealthCheckOutcome leadScore() throws QException
+   {
+      List<QRecord> rows = new QueryAction().execute(new QueryInput(JobState.TABLE_NAME).withFilter(new QQueryFilter(
+         new QFilterCriteria("name", QCriteriaOperator.EQUALS, CalculateLeadScoresProcess.NAME)).withLimit(1))).getRecords();
+      Instant last = rows.isEmpty() ? null : rows.getFirst().getValueInstant("lastSuccess");
+      return (last == null || last.isBefore(Instant.now().minus(3, ChronoUnit.HOURS))
+         ? HealthCheckOutcome.degraded("No lead score pass succeeded in the last 3 hours")
+         : HealthCheckOutcome.up("Lead scores are current"));
+   }
+}

src/main/java/com/kingsrook/qbits/crm/privacy/CrmPersonalData.java

@@ -0,0 +1,247 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.privacy;
+
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEntityType;
+import com.kingsrook.qqq.backend.core.actions.tables.DeleteAction;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.ActionFlag;
+import com.kingsrook.qqq.backend.core.model.actions.tables.delete.DeleteInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QQueryFilter;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Erases the CRM's copies of a contact's personal data using tenant-scoped actions.
+ *******************************************************************************/
+public final class CrmPersonalData
+{
+   /*******************************************************************************
+    ** Narrow consent exception: only replacing evidence text with "erased".
+    *******************************************************************************/
+   public enum ErasureFlag implements ActionFlag
+   {
+      REDACT_CONSENT
+   }
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmPersonalData()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Erase linked data before the contact so retries still have the original email.
+    *******************************************************************************/
+   public static void erase(Integer contactId) throws QException
+   {
+      QRecord contact = GetAction.execute("crm_contact", contactId);
+      if(contact == null)
+      {
+         throw (new QException("Contact not found: " + contactId));
+      }
+      List<Serializable> emails = new ArrayList<>();
+      for(String field : List.of("email", "secondaryEmail"))
+      {
+         if(contact.getValueString(field) != null)
+         {
+            emails.add(contact.getValueString(field));
+         }
+      }
+      // Two queries avoid OR filters crossing tenant scopes and make retries idempotent.
+      eraseForms(new QQueryFilter(new QFilterCriteria("contactId", QCriteriaOperator.EQUALS, contactId)));
+      if(!emails.isEmpty())
+      {
+         eraseForms(new QQueryFilter(new QFilterCriteria("email", QCriteriaOperator.IN, emails)));
+      }
+      for(QRecord row : linked("crm_email_list_member", contactId))
+      {
+         redact("crm_email_list_member", row, "email", "firstName", "confirmationTokenHash", "consentText");
+      }
+      for(QRecord row : linked("crm_email_message", contactId))
+      {
+         redact("crm_email_message", row, "fromAddress", "fromName", "toAddresses", "ccAddresses", "bccAddresses", "subject", "bodyHtml", "bodyText");
+      }
+      for(QRecord row : linked("crm_activity", contactId))
+      {
+         redact("crm_activity", row, "description", "subject");
+         for(QRecord message : query("crm_email_message", new QQueryFilter(new QFilterCriteria("activityId", QCriteriaOperator.EQUALS, row.getValue("id")))))
+         {
+            redact("crm_email_message", message, "fromAddress", "fromName", "toAddresses", "ccAddresses", "bccAddresses", "subject", "bodyHtml", "bodyText");
+         }
+      }
+      for(QRecord row : linked("crm_consent_record", contactId))
+      {
+         checkedUpdate("crm_consent_record", new QRecord().withValue("id", row.getValue("id")).withValue("consentText", "erased"));
+         redactAudit("crm_consent_record", row.getValue("id"));
+      }
+      for(QRecord row : linked("crm_sequence_enrollment", contactId))
+      {
+         checkedUpdate("crm_sequence_enrollment", new QRecord().withValue("id", row.getValue("id"))
+            .withValue("status", CrmEnrollmentStatus.UNENROLLED.getId()).withValue("nextStepDate", null));
+         redactAudit("crm_sequence_enrollment", row.getValue("id"));
+      }
+      for(QRecord row : query("crm_external_mapping", new QQueryFilter(
+         new QFilterCriteria("entityType", QCriteriaOperator.EQUALS, CrmEntityType.CONTACT.getId()),
+         new QFilterCriteria("entityId", QCriteriaOperator.EQUALS, contactId))))
+      {
+         var deleted = new DeleteAction().execute(new DeleteInput("crm_external_mapping").withPrimaryKey(row.getValue("id")).withOmitDmlAudit(true));
+         if(deleted.getDeletedRecordCount() != 1)
+         {
+            throw (new QException("CRM erase could not delete an external mapping"));
+         }
+         redactAudit("crm_external_mapping", row.getValue("id"));
+      }
+      redact("crm_contact", contact, "firstName", "lastName", "phone", "mobilePhone", "secondaryEmail", "addressLine1", "addressLine2",
+         "city", "state", "postalCode", "country", "timezone", "jobTitle", "department", "website", "linkedinUrl", "description");
+      checkedUpdate("crm_contact", new QRecord().withValue("id", contactId).withValue("email", "anonymized-" + contactId + "@removed.invalid")
+         .withValue("doNotEmail", true).withValue("doNotCall", true));
+      CrmRecords.insert("crm_consent_record", new QRecord().withValue("contactId", contactId)
+         .withValue("consentType", CrmConsentType.DATA_PROCESSING.getId()).withValue("status", CrmConsentStatus.WITHDRAWN.getId())
+         .withValue("consentText", "Erased on " + LocalDate.now(ZoneOffset.UTC)).withValue("source", "GDPR erasure").withValue("consentDate", Instant.now()));
+   }
+
+
+   /*******************************************************************************
+    ** Erase both direct and email-matched web leads.
+    *******************************************************************************/
+   private static void eraseForms(QQueryFilter filter) throws QException
+   {
+      for(QRecord row : query("crm_form_submission", filter))
+      {
+         redact("crm_form_submission", row, "firstName", "lastName", "email", "phone", "message", "clientHash", "visitorKey", "consentText", "company");
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Collect rows through core record locks, never through a backend bypass.
+    *******************************************************************************/
+   private static List<QRecord> linked(String table, Integer contactId) throws QException
+   {
+      return (query(table, new QQueryFilter(new QFilterCriteria("contactId", QCriteriaOperator.EQUALS, contactId))));
+   }
+
+
+   /*******************************************************************************
+    ** Page queries to avoid the backend's default result limit silently omitting PII.
+    *******************************************************************************/
+   private static List<QRecord> query(String table, QQueryFilter filter) throws QException
+   {
+      List<QRecord> result = new ArrayList<>();
+      Serializable after = null;
+      while(true)
+      {
+         QQueryFilter page = filter.clone().withOrderBy(new QFilterOrderBy("id")).withLimit(250);
+         if(after != null)
+         {
+            page.withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, after));
+         }
+         List<QRecord> rows = new QueryAction().execute(new QueryInput(table).withFilter(page)).getRecords();
+         result.addAll(rows);
+         if(rows.size() < 250)
+         {
+            return (result);
+         }
+         after = rows.getLast().getValue("id");
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Keep required fields nonempty; never audit the original values during erasure.
+    *******************************************************************************/
+   private static void redact(String table, QRecord row, String... fields) throws QException
+   {
+      QRecord update = new QRecord().withValue("id", row.getValue("id"));
+      for(String field : fields)
+      {
+         boolean required = Boolean.TRUE.equals(QContext.getQInstance().getTable(table).getField(field).getIsRequired());
+         update.withValue(field, required || field.equals("firstName") || field.equals("lastName") ? "[ANONYMIZED]" : null);
+      }
+      checkedUpdate(table, update);
+      redactAudit(table, row.getValue("id"));
+   }
+
+
+   /*******************************************************************************
+    ** A failed write must fail erasure; never report a partially erased contact as done.
+    *******************************************************************************/
+   private static void checkedUpdate(String table, QRecord update) throws QException
+   {
+      var output = new UpdateAction().execute(new UpdateInput(table).withRecord(update).withOmitDmlAudit(true).withFlag(ErasureFlag.REDACT_CONSENT));
+      if(output.getRecords().isEmpty() || output.getRecords().stream().anyMatch(row -> row.getErrors() != null && !row.getErrors().isEmpty()))
+      {
+         throw (new QException("CRM erase could not redact " + table));
+      }
+   }
+
+
+   /*******************************************************************************
+    ** RC.6 core audits resolve table ids through auditTable. Redact both values and
+    ** human-readable messages, which can embed old record labels and personal values.
+    *******************************************************************************/
+   private static void redactAudit(String table, Serializable recordId) throws QException
+   {
+      if(QContext.getQInstance().getTable("auditTable") == null || QContext.getQInstance().getTable("audit") == null
+         || QContext.getQInstance().getTable("auditDetail") == null)
+      {
+         return;
+      }
+      for(QRecord auditTable : query("auditTable", new QQueryFilter(new QFilterCriteria("name", QCriteriaOperator.EQUALS, table))))
+      {
+         for(QRecord audit : query("audit", new QQueryFilter(
+            new QFilterCriteria("auditTableId", QCriteriaOperator.EQUALS, auditTable.getValue("id")),
+            new QFilterCriteria("recordId", QCriteriaOperator.EQUALS, recordId))))
+         {
+            for(QRecord detail : query("auditDetail", new QQueryFilter(new QFilterCriteria("auditId", QCriteriaOperator.EQUALS, audit.getValue("id")))))
+            {
+               checkedUpdate("auditDetail", new QRecord().withValue("id", detail.getValue("id"))
+                  .withValue("oldValue", "erased").withValue("newValue", "erased").withValue("message", "erased"));
+            }
+            checkedUpdate("audit", new QRecord().withValue("id", audit.getValue("id")).withValue("message", "Personal data erased"));
+         }
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/scoring/AutoAssignCustomizer.java

@@ -0,0 +1,65 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.scoring;
+
+
+import java.util.List;
+import com.kingsrook.qbits.crm.core.model.enums.CrmAssignableEntity;
+import com.kingsrook.qqq.backend.core.actions.customizers.AbstractPostInsertCustomizer;
+import com.kingsrook.qqq.backend.core.alerts.NotificationAudience;
+import com.kingsrook.qqq.backend.core.alerts.NotificationSignal;
+import com.kingsrook.qqq.backend.core.alerts.QAlerts;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** Apply assignment rules to new contacts and deals without replacing explicit owners.
+ *******************************************************************************/
+public class AutoAssignCustomizer extends AbstractPostInsertCustomizer
+{
+   @Override
+   public List<QRecord> apply(List<QRecord> records) throws QException
+   {
+      for(QRecord row : records)
+      {
+         if(row.getErrors() != null && !row.getErrors().isEmpty())
+         {
+            continue;
+         }
+         String owner = row.getValueString("ownerUserId");
+         if(owner == null || "system".equals(owner))
+         {
+            CrmAutoAssign.Result result = CrmAutoAssign.assign("crm_contact".equals(insertInput.getTableName())
+               ? CrmAssignableEntity.CONTACT : CrmAssignableEntity.DEAL, row.getValueInteger("id"));
+            if("ASSIGNED".equals(result.action()))
+            {
+               row.setValue("ownerUserId", result.assignedUserId());
+               QAlerts.notify(new NotificationSignal("CRM lead assigned").withSourceName("crm.lead.assigned")
+                  .withSourceKey(insertInput.getTableName() + ":" + row.getValue("id"))
+                  .withSourceTableName(insertInput.getTableName()).withSourceRecordId(row.getValueString("id"))
+                  .withAudience(NotificationAudience.user(result.assignedUserId())), insertInput.getTransaction());
+            }
+         }
+      }
+      return (records);
+   }
+}

src/main/java/com/kingsrook/qbits/crm/scoring/JobState.java

@@ -0,0 +1,49 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.scoring;
+
+
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerInterface;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.UniqueKey;
+
+
+/*******************************************************************************
+ ** Small persistent maintenance checkpoints, including the last full score pass.
+ *******************************************************************************/
+public class JobState implements MetaDataProducerInterface<QTableMetaData>
+{
+   public static final String TABLE_NAME = "crm_job_state";
+
+   @Override
+   public QTableMetaData produce(QInstance instance)
+   {
+      return (new QTableMetaData().withName(TABLE_NAME).withLabel("Job State").withPrimaryKeyField("id")
+         .withField(new QFieldMetaData("id", QFieldType.INTEGER).withIsEditable(false))
+         .withField(new QFieldMetaData("name", QFieldType.STRING).withIsRequired(true).withMaxLength(250))
+         .withField(new QFieldMetaData("lastSuccess", QFieldType.DATE_TIME))
+         .withField(new QFieldMetaData("lastFullPass", QFieldType.DATE_TIME))
+         .withUniqueKey(new UniqueKey("name")));
+   }
+}

src/main/java/com/kingsrook/qbits/crm/scoring/processes/CalculateLeadScoresProcess.java

@@ -26,22 +26,29 @@
 package com.kingsrook.qbits.crm.scoring.processes;
 
 
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.ZoneOffset;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
+import com.kingsrook.qbits.crm.core.CrmRecords;
 import com.kingsrook.qbits.crm.core.model.Company;
 import com.kingsrook.qbits.crm.core.model.Contact;
 import com.kingsrook.qbits.crm.core.model.enums.CrmScoreOperator;
+import com.kingsrook.qbits.crm.deals.CrmDealNotifications;
+import com.kingsrook.qbits.crm.scoring.JobState;
 import com.kingsrook.qbits.crm.scoring.model.LeadScoreRule;
 import com.kingsrook.qqq.backend.core.actions.processes.BackendStep;
-import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
 import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
 import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.logging.QLogger;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
 import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput;
-import com.kingsrook.qqq.backend.core.model.actions.tables.get.GetOutput;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QCriteriaOperator;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterCriteria;
 import com.kingsrook.qqq.backend.core.model.actions.tables.query.QFilterOrderBy;
@@ -83,7 +90,6 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
          .withIsHidden(true)
          .withLabel("Calculate Lead Scores")
          .withIcon(new QIcon().withName("score"))
-         // Scheduling is configured by the host application via ScheduledJob records
          .withStepList(List.of(
             new QBackendStepMetaData()
                .withName("execute")
@@ -99,6 +105,18 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
    @Override
    public void run(RunBackendStepInput input, RunBackendStepOutput output) throws QException
    {
+      ////////////////////////////////////////////////////////////////////////
+      // modifyDate is kept at millisecond precision; a microsecond watermark //
+      // would skip a change made in the same millisecond the pass started.   //
+      ////////////////////////////////////////////////////////////////////////
+      Instant startedAt = Instant.now().truncatedTo(ChronoUnit.MILLIS);
+      List<QRecord> states = new QueryAction().execute(new QueryInput(JobState.TABLE_NAME)
+         .withFilter(new QQueryFilter(new QFilterCriteria("name", QCriteriaOperator.EQUALS, NAME)))).getRecords();
+      QRecord state = states.isEmpty() ? new QRecord().withValue("name", NAME) : states.getFirst();
+      Instant lastSuccess = state.getValueInstant("lastSuccess");
+      Instant lastFullPass = state.getValueInstant("lastFullPass");
+      boolean full = Boolean.TRUE.equals(input.getValueBoolean("fullRecalc")) || lastSuccess == null || lastFullPass == null
+         || !lastFullPass.isAfter(startedAt.minus(24, ChronoUnit.HOURS));
       ///////////////////////////////////////////////
       // load all active rules ordered by sort     //
       ///////////////////////////////////////////////
@@ -131,6 +149,10 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
             filter.withCriteria(new QFilterCriteria("id", QCriteriaOperator.GREATER_THAN, lastId));
          }
 
+         if(!full)
+         {
+            filter.withCriteria(new QFilterCriteria("modifyDate", QCriteriaOperator.GREATER_THAN_OR_EQUALS, lastSuccess));
+         }
          QueryOutput contactsQuery = new QueryAction().execute(
             new QueryInput(Contact.TABLE_NAME).withFilter(filter));
 
@@ -139,15 +161,20 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
             break;
          }
 
+         Map<Integer, QRecord> companies = loadCompanies(contactsQuery.getRecords());
+         List<QRecord> changes = new ArrayList<>();
          for(QRecord contactRecord : contactsQuery.getRecords())
          {
             totalContacts++;
-            if(recalculate(contactRecord, rules))
+            QRecord change = calculateChange(contactRecord, rules, companies);
+            if(change != null)
             {
-               updatedCount++;
+               changes.add(change);
             }
             lastId = contactRecord.getValueInteger("id");
          }
+         writeScores(changes);
+         updatedCount += changes.size();
 
          /////////////////////////////////////////////
          // if page was not full, we are done       //
@@ -158,6 +185,21 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
          }
       }
 
+      CrmDealNotifications.checkRotting();
+      state.withValue("lastSuccess", startedAt);
+      if(full)
+      {
+         state.withValue("lastFullPass", startedAt);
+      }
+      if(states.isEmpty())
+      {
+         CrmRecords.insert(JobState.TABLE_NAME, state);
+      }
+      else
+      {
+         CrmRecords.update(JobState.TABLE_NAME, state);
+      }
+      output.addValue("fullRecalc", full);
       output.addValue("updatedCount", updatedCount);
       output.addValue("totalContacts", totalContacts);
       output.addValue("totalRules", rules.size());
@@ -173,18 +215,19 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
       List<LeadScoreRule> rules = new QueryAction().execute(new QueryInput(LeadScoreRule.TABLE_NAME)
          .withFilter(new QQueryFilter(new QFilterCriteria("isActive", QCriteriaOperator.EQUALS, true))
             .withOrderBy(new QFilterOrderBy("sortOrder")))).getRecords().stream().map(LeadScoreRule::new).toList();
-      recalculate(contact, rules);
+      QRecord change = calculateChange(contact, rules, loadCompanies(List.of(contact)));
+      writeScores(change == null ? List.of() : List.of(change));
    }
 
    /*******************************************************************************
-    ** Write only changed scores; return whether a write was needed.
+    ** Compute a score update only when the result changed.
     *******************************************************************************/
-   private boolean recalculate(QRecord contact, List<LeadScoreRule> rules) throws QException
+   private QRecord calculateChange(QRecord contact, List<LeadScoreRule> rules, Map<Integer, QRecord> companies) throws QException
    {
       int score = 0;
       for(LeadScoreRule rule : rules)
       {
-         if(evaluateRule(rule, contact))
+         if(evaluateRule(rule, contact, companies))
          {
             score += rule.getScoreAdjustment();
          }
@@ -192,11 +235,27 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
       Integer current = contact.getValueInteger("leadScore");
       if(Objects.equals(current == null ? 0 : current, score))
       {
-         return (false);
+         return (null);
+      }
+      return (new QRecord().withValue("id", contact.getValue("id")).withValue("leadScore", score));
+   }
+
+   /*******************************************************************************
+    ** Batch score writes so core audit label resolution also operates per page.
+    *******************************************************************************/
+   private void writeScores(List<QRecord> changes) throws QException
+   {
+      if(changes.isEmpty())
+      {
+         return;
+      }
+      UpdateInput update = new UpdateInput(Contact.TABLE_NAME).withOmitModifyDateUpdate(true);
+      update.setRecords(changes);
+      var updated = new UpdateAction().execute(update).getRecords();
+      if(updated.isEmpty() || updated.stream().anyMatch(row -> row.getErrors() != null && !row.getErrors().isEmpty()))
+      {
+         throw (new QException("Lead score update was rejected"));
       }
-      new UpdateAction().execute(new UpdateInput(Contact.TABLE_NAME)
-         .withRecord(new QRecord().withValue("id", contact.getValue("id")).withValue("leadScore", score)));
-      return (true);
    }
 
 
@@ -204,7 +263,7 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
     ** Evaluate a single rule against a contact record. Supports dot-notation
     ** field paths for related entities (e.g., "company.industry").
     ***************************************************************************/
-   private boolean evaluateRule(LeadScoreRule rule, QRecord contactRecord)
+   private boolean evaluateRule(LeadScoreRule rule, QRecord contactRecord, Map<Integer, QRecord> companies)
    {
       CrmScoreOperator operator = CrmScoreOperator.getById(rule.getOperator());
       if(operator == null)
@@ -213,7 +272,7 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
       }
 
       String fieldPath = rule.getFieldPath();
-      String actualValue = resolveFieldValue(fieldPath, contactRecord);
+      String actualValue = resolveFieldValue(fieldPath, contactRecord, companies);
       String expectedValue = rule.getFieldValue();
 
       switch(operator)
@@ -233,6 +292,10 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
          case LT:
             return (compareNumeric(actualValue, expectedValue) < 0);
 
+         case DAYS_AGO_GT:
+         case DAYS_AGO_LT:
+            return (compareAge(actualValue, expectedValue, operator));
+
          case IS_SET:
             return (StringUtils.hasContent(actualValue));
 
@@ -272,48 +335,54 @@ public class CalculateLeadScoresProcess implements BackendStep, MetaDataProducer
     ** for related entity fields (e.g., "company.industry" loads the contact's
     ** company record and returns its "industry" field).
     ***************************************************************************/
-   private String resolveFieldValue(String fieldPath, QRecord contactRecord)
+   private String resolveFieldValue(String fieldPath, QRecord contactRecord, Map<Integer, QRecord> companies)
    {
       if(fieldPath == null || !fieldPath.contains("."))
       {
          return (contactRecord.getValueString(fieldPath));
       }
-
       String[] parts = fieldPath.split("\\.", 2);
-      String prefix    = parts[0];
-      String fieldName = parts[1];
-
-      try
+      if("company".equalsIgnoreCase(parts[0]))
       {
-         if("company".equalsIgnoreCase(prefix))
-         {
-            Integer companyId = contactRecord.getValueInteger("companyId");
-            if(companyId == null)
-            {
-               return (null);
-            }
-
-            GetOutput companyOutput = new GetAction().execute(
-               new GetInput(Company.TABLE_NAME).withPrimaryKey(companyId));
-
-            if(companyOutput.getRecord() == null)
-            {
-               return (null);
-            }
-
-            return (companyOutput.getRecord().getValueString(fieldName));
-         }
-         else
-         {
-            LOG.warn("Unsupported dot-notation prefix in lead score rule fieldPath: " + prefix);
-            return (null);
-         }
-      }
-      catch(Exception e)
-      {
-         LOG.warn("Error resolving dot-notation field [" + fieldPath + "] for contact", e);
-         return (null);
+         QRecord company = companies.get(contactRecord.getValueInteger("companyId"));
+         return (company == null ? null : company.getValueString(parts[1]));
       }
+      LOG.warn("Unsupported dot-notation prefix in lead score rule fieldPath: " + parts[0]);
+      return (null);
    }
 
+   /*******************************************************************************
+    ** One company query per page, shared by every rule and contact in that page.
+    *******************************************************************************/
+   private Map<Integer, QRecord> loadCompanies(List<QRecord> contacts) throws QException
+   {
+      List<Integer> ids = contacts.stream().map(row -> row.getValueInteger("companyId")).filter(Objects::nonNull).distinct().toList();
+      Map<Integer, QRecord> companies = new HashMap<>();
+      if(!ids.isEmpty())
+      {
+         for(QRecord company : new QueryAction().execute(new QueryInput(Company.TABLE_NAME)
+            .withFilter(new QQueryFilter(new QFilterCriteria("id", QCriteriaOperator.IN, ids)))).getRecords())
+         {
+            companies.put(company.getValueInteger("id"), company);
+         }
+      }
+      return (companies);
+   }
+
+   /*******************************************************************************
+    ** Compare instants or UTC calendar dates with the strict N-days-ago boundary.
+    *******************************************************************************/
+   private boolean compareAge(String actual, String expected, CrmScoreOperator operator)
+   {
+      try
+      {
+         Instant date = actual.length() == 10 ? LocalDate.parse(actual).atStartOfDay(ZoneOffset.UTC).toInstant() : Instant.parse(actual);
+         Instant threshold = Instant.now().minus(Long.parseLong(expected), ChronoUnit.DAYS);
+         return (operator == CrmScoreOperator.DAYS_AGO_GT ? date.isBefore(threshold) : date.isAfter(threshold));
+      }
+      catch(RuntimeException e)
+      {
+         return (false);
+      }
+   }
 }

src/main/java/com/kingsrook/qbits/crm/security/CrmDataPolicy.java

@@ -0,0 +1,137 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.security;
+
+
+import java.util.List;
+import java.util.Map;
+import com.kingsrook.qbits.crm.CrmAppMetaData;
+import com.kingsrook.qbits.crm.CrmQBitConfig;
+import com.kingsrook.qqq.backend.core.actions.ai.AiFieldMetaData;
+import com.kingsrook.qqq.backend.core.actions.ai.DataClassification;
+import com.kingsrook.qqq.backend.core.model.metadata.MetaDataProducerMultiOutput;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.layout.QIcon;
+import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType;
+import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
+
+
+/*******************************************************************************
+ ** CRM field classification and optional tenant record locks.
+ *******************************************************************************/
+public final class CrmDataPolicy
+{
+   private static final Map<String, List<String>> PERSONAL_FIELDS = Map.of(
+      "crm_contact", List.of("firstName", "lastName", "email", "secondaryEmail", "phone", "mobilePhone", "addressLine1",
+         "addressLine2", "city", "state", "postalCode", "country", "linkedinUrl", "timezone", "jobTitle", "department", "website", "description"),
+      "crm_company", List.of("phone", "addressLine1", "addressLine2", "city", "state", "postalCode", "country"),
+      "crm_form_submission", List.of("firstName", "lastName", "email", "phone", "message", "clientHash", "visitorKey", "consentText", "company"),
+      "crm_email_list_member", List.of("email", "firstName", "consentText", "confirmationTokenHash"),
+      "crm_email_message", List.of("fromAddress", "fromName", "toAddresses", "ccAddresses", "bccAddresses", "subject"),
+      "crm_consent_record", List.of("consentText"),
+      "crm_activity", List.of("description"));
+
+   private static final Map<String, String> PARENTS = Map.ofEntries(
+      Map.entry("crm_pipeline_stage", "crm_pipeline"),
+      Map.entry("crm_assignment_rule_member", "crm_assignment_rule"),
+      Map.entry("crm_consent_record", "crm_contact"),
+      Map.entry("crm_email_list_member", "crm_contact"),
+      Map.entry("crm_email_message", "crm_contact"),
+      Map.entry("crm_sequence_enrollment", "crm_contact"),
+      Map.entry("crm_sequence_step", "crm_email_sequence"),
+      Map.entry("crm_activity_participant", "crm_activity"),
+      Map.entry("crm_deal_contact", "crm_deal"),
+      Map.entry("crm_deal_product", "crm_deal"),
+      Map.entry("crm_deal_stage_history", "crm_deal"));
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmDataPolicy()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Apply after joins have their final names, before backend name inference.
+    *******************************************************************************/
+   public static void apply(MetaDataProducerMultiOutput output, QInstance instance, CrmQBitConfig config)
+   {
+      String keyType = config.getTenantSecurityKeyType();
+      if(keyType != null && instance.getSecurityKeyType(keyType) == null)
+      {
+         output.add(new QSecurityKeyType().withName(keyType).withAllAccessKeyName(config.getTenantAllAccessKeyName()));
+      }
+      for(QTableMetaData table : output.getEach(QTableMetaData.class))
+      {
+         for(String name : PERSONAL_FIELDS.getOrDefault(table.getName(), List.of()))
+         {
+            QFieldMetaData field = table.getField(name);
+            if(field == null)
+            {
+               throw (new IllegalStateException("Unknown CRM PII field: " + table.getName() + "." + name));
+            }
+            AiFieldMetaData ai = AiFieldMetaData.of(field);
+            field.withSupplementalMetaData((ai == null ? new AiFieldMetaData() : ai).withClassification(DataClassification.PII));
+         }
+         if(keyType == null)
+         {
+            continue;
+         }
+         RecordSecurityLock lock = new RecordSecurityLock().withSecurityKeyType(keyType);
+         String parent = PARENTS.get(table.getName());
+         if(parent == null)
+         {
+            // Polymorphic external mappings and internal job checkpoints need a direct key too.
+            table.withField(new QFieldMetaData("tenantKey", QFieldType.STRING).withMaxLength(250));
+            if(table.getSections() != null && !table.getSections().isEmpty())
+            {
+               table.withSection(new QFieldSection("crm_tenancy", "Tenancy", new QIcon("lock"), Tier.T3, List.of("tenantKey")));
+            }
+            lock.withFieldName("tenantKey");
+         }
+         else
+         {
+            QJoinMetaData join = output.getEach(QJoinMetaData.class).stream()
+               .filter(candidate -> parent.equals(candidate.getLeftTable()) && table.getName().equals(candidate.getRightTable()))
+               .findFirst().orElseThrow(() -> new IllegalStateException("Missing tenant parent join for " + table.getName()));
+            lock.withFieldName(parent + ".tenantKey").withJoinNameChain(List.of(join.getName()));
+         }
+         table.withRecordSecurityLock(lock);
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Main and settings tables exposed through the host API.
+    *******************************************************************************/
+   public static boolean isPublishedTable(String name)
+   {
+      return (CrmAppMetaData.MAIN_TABLES.contains(name) || CrmAppMetaData.SETTINGS_TABLES.contains(name));
+   }
+}

src/main/java/com/kingsrook/qbits/crm/security/CrmPermissions.java

@@ -49,7 +49,7 @@ public final class CrmPermissions
    public static final List<String> ALL = List.of(APP_ACCESS, READ, WRITE, MANAGE, MANAGE_READ, MANAGE_WRITE, ADMIN, ADMIN_READ, ADMIN_WRITE);
 
    private static final Set<String> SETTINGS_TABLES = Set.of(
-      "crm_pipeline", "crm_product", "crm_email_template", "crm_email_sequence",
+      "crm_job_state", "crm_pipeline", "crm_product", "crm_email_template", "crm_email_sequence",
       "crm_lead_score_rule", "crm_assignment_rule", "crm_sales_goal", "crm_lifecycle_stage",
       "crm_lead_source", "crm_industry", "crm_activity_type", "crm_activity_outcome",
       "crm_contact_role", "crm_win_loss_reason");
@@ -58,7 +58,7 @@ public final class CrmPermissions
       "crm_merge_contacts", "crm_merge_companies", "crm_bulk_assign_owner",
       "crm_subscribe_to_list", "crm_unsubscribe_from_list", "crm_enroll_in_sequence",
       "crm_unenroll_from_sequence", "crm_process_sequence_steps", "crm_assign_company_owner",
-      "crm_transfer_ownership", "crm_activate_sequence", "crm_pause_sequence");
+      "crm_transfer_ownership", "crm_activate_sequence", "crm_pause_sequence", "crm_sync_email_delivery", "crm_expire_consents", "crm_calculate_lead_scores");
 
 
 

src/main/java/com/kingsrook/qbits/crm/security/CrmRelationshipValidator.java

@@ -0,0 +1,86 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.security;
+
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizerInterface;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.statusmessages.BadInputStatusMessage;
+
+
+/*******************************************************************************
+ ** CRM relationship invariants, enforced for inserts and partial updates.
+ *******************************************************************************/
+public class CrmRelationshipValidator implements TableCustomizerInterface
+{
+   @Override
+   public List<QRecord> preInsertOrUpdate(AbstractActionInput input, List<QRecord> records, boolean isPreview,
+      Optional<List<QRecord>> oldRecords) throws QException
+   {
+      Map<Object, QRecord> oldById = new HashMap<>();
+      oldRecords.orElse(List.of()).forEach(row -> oldById.put(row.getValue("id"), row));
+      for(QRecord record : records)
+      {
+         QRecord effective = new QRecord();
+         QRecord old = oldById.get(record.getValue("id"));
+         if(old != null)
+         {
+            effective.getValues().putAll(old.getValues());
+         }
+         effective.getValues().putAll(record.getValues());
+         if(effective.getValues().containsKey("pipelineStageId"))
+         {
+            validate(record, effective, "pipelineStageId", "pipelineId", "crm_pipeline_stage");
+         }
+         if(effective.getValues().containsKey("outcomeId"))
+         {
+            validate(record, effective, "outcomeId", "activityTypeId", "crm_activity_outcome");
+         }
+      }
+      return (records);
+   }
+
+
+   /*******************************************************************************
+    ** Missing optional choices are allowed; populated choices must belong to the parent.
+    *******************************************************************************/
+   private void validate(QRecord record, QRecord effective, String childField, String parentField, String source) throws QException
+   {
+      if(effective.getValue(childField) == null)
+      {
+         return;
+      }
+      QRecord choice = GetAction.execute(source, effective.getValue(childField));
+      if(choice == null || effective.getValue(parentField) == null
+         || !Objects.equals(choice.getValueInteger(parentField), effective.getValueInteger(parentField)))
+      {
+         record.addError(new BadInputStatusMessage("Choose a value belonging to the selected " + parentField + "."));
+      }
+   }
+}

src/main/java/com/kingsrook/qbits/crm/widgets/CrmContactTimelineRenderer.java

@@ -22,19 +22,26 @@
 package com.kingsrook.qbits.crm.widgets;
 
 
+import java.time.DateTimeException;
 import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
 import com.kingsrook.qqq.backend.core.actions.ai.output.AiLinkBuilder;
 import com.kingsrook.qqq.backend.core.actions.dashboard.widgets.AbstractWidgetRenderer;
 import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
 import com.kingsrook.qqq.backend.core.exceptions.QException;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
 import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetOutput;
 import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
 
 
 /*******************************************************************************
@@ -70,9 +77,41 @@ public class CrmContactTimelineRenderer extends AbstractWidgetRenderer
             String kind = Map.of("crm_activity", "Activity", "crm_email_message", "Email message",
                "crm_form_submission", "Web lead", "crm_consent_record", "Consent record").get(table);
             String detail = Objects.toString(record.getValue("subject"), Objects.toString(record.getValue("email"), kind));
-            rows.add(CrmHomeRenderer.row(AiLinkBuilder.recordHref(table, record.getValue("id")), record.getValue("createDate"), kind, detail));
+            rows.add(CrmHomeRenderer.row(AiLinkBuilder.recordHref(table, record.getValue("id")), formatDate(record.getValueInstant("createDate")), kind, detail));
          }
       }
       return (new RenderWidgetOutput(CrmHomeRenderer.table(rows, "Recorded", "Kind", "Details")));
    }
+
+
+   /*******************************************************************************
+    ** Prefer the session timezone (including DST), then offset, otherwise UTC.
+    *******************************************************************************/
+   static String formatDate(Instant instant)
+   {
+      if(instant == null)
+      {
+         return ("");
+      }
+      ZoneId zone = ZoneOffset.UTC;
+      QSession session = QContext.getQSession();
+      String timezone = session == null ? null : session.getValue(QSession.VALUE_KEY_USER_TIMEZONE);
+      String offset = session == null ? null : session.getValue(QSession.VALUE_KEY_USER_TIMEZONE_OFFSET_MINUTES);
+      try
+      {
+         if(timezone != null && !timezone.isBlank())
+         {
+            zone = ZoneId.of(timezone);
+         }
+         else if(offset != null && !offset.isBlank())
+         {
+            zone = ZoneOffset.ofTotalSeconds(Math.multiplyExact(60, Integer.parseInt(offset)));
+         }
+      }
+      catch(DateTimeException | IllegalArgumentException | ArithmeticException e)
+      {
+         zone = ZoneOffset.UTC;
+      }
+      return (DateTimeFormatter.ofPattern("MMM d, uuuu h:mm a", Locale.US).withZone(zone).format(instant));
+   }
 }

src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeRenderer.java

@@ -25,6 +25,8 @@ package com.kingsrook.qbits.crm.widgets;
 import java.io.Serializable;
 import java.math.BigDecimal;
 import java.math.RoundingMode;
+import java.text.DecimalFormat;
+import java.text.DecimalFormatSymbols;
 import java.time.Instant;
 import java.time.LocalDate;
 import java.time.ZoneOffset;
@@ -33,6 +35,7 @@ import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Objects;
 import com.kingsrook.qbits.crm.core.model.enums.CrmFormConversionStatus;
@@ -89,6 +92,8 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
       {
          case "crm_today":
             return (new RenderWidgetOutput(new ParentWidgetData().withChildWidgetNameList(CrmHomeWidgets.TODAY).withLabel("Today")));
+         case "crm_setup":
+            return (new RenderWidgetOutput(setup()));
          case "crm_open_pipeline":
             return (new RenderWidgetOutput(statistic(sum(DEAL, dealStatus(false), AMOUNT), true)));
          case "crm_won_month":
@@ -118,11 +123,20 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
 
 
    /*******************************************************************************
-    ** Preserve decimals and large counts in the standard statistics renderer.
+    ** Format statistics with the configured base currency in the value.
     *******************************************************************************/
-   private StatisticsData statistic(BigDecimal value, boolean currency)
+   private StatisticsData statistic(BigDecimal value, boolean currency) throws QException
    {
-      return (new StatisticsData().withCount(value).withCountContext(currency ? "base currency" : null));
+      String prefix = "";
+      if(currency)
+      {
+         List<QRecord> base = query("crm_currency", equalsFilter("isBaseCurrency", true), "id", true, 1);
+         if(!base.isEmpty() && base.getFirst().getValueString("currencyCode") != null)
+         {
+            prefix = base.getFirst().getValueString("currencyCode") + " ";
+         }
+      }
+      return (new StatisticsData().withCount(prefix + formatAmount(value)));
    }
 
 
@@ -197,7 +211,7 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
 
 
    /*******************************************************************************
-    ** Stage and deal count share one column, keeping both monetary columns.
+    ** Separate the stage label, integer count and weighted base-currency amount.
     *******************************************************************************/
    private TableData pipeline(RenderWidgetInput input) throws QException
    {
@@ -220,10 +234,10 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
          {
             BigDecimal[] values = totals.getOrDefault(stage.getValue("id"), new BigDecimal[] {BigDecimal.ZERO, BigDecimal.ZERO, BigDecimal.ZERO});
             String href = AiLinkBuilder.recordHref(STAGE, stage.getValue("id"));
-            rows.add(row(href, stage.getValueString("name") + " (" + values[0].toPlainString() + " deals)", values[1], values[2]));
+            rows.add(row(href, stage.getValueString("name"), values[0].toBigIntegerExact(), formatAmount(values[2])));
          }
       }
-      TableData data = table(rows, "Stage / deals", "Amount (base)", "Weighted amount (base)");
+      TableData data = table(rows, "Stage", "Deals", "Weighted amount");
       if(pipelines.size() > 1)
       {
          data.withDropdownNameList(List.of("pipelineId")).withDropdownLabelList(List.of("Pipeline"))
@@ -235,6 +249,22 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
    }
 
 
+   /*******************************************************************************
+    ** The Setup card: each piece of configuration the CRM needs, its state and the
+    ** next step, every cell linking to the table that fixes it.
+    *******************************************************************************/
+   private TableData setup() throws QException
+   {
+      List<Map<String, Object>> rows = new ArrayList<>();
+      for(CrmSetupStatus.Item item : CrmSetupStatus.load())
+      {
+         rows.add(row(AiLinkBuilder.filteredTableHref(item.tableName(), new QQueryFilter()), item.label(),
+            item.state().getLabel() + ": " + item.detail(), item.nextStep() == null ? "Nothing to do" : item.nextStep()));
+      }
+      return (table(rows, "Setup", "Status", "Next step"));
+   }
+
+
    /*******************************************************************************
     ** Six calendar buckets, including the current month, with empty months kept.
     *******************************************************************************/
@@ -246,7 +276,7 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
          LocalDate start = today.withDayOfMonth(1).plusMonths(month);
          QQueryFilter filter = period(dealStatus(false), "expectedCloseDate", start, start.plusMonths(1));
          BigDecimal[] totals = totals(filter);
-         rows.add(row(AiLinkBuilder.filteredTableHref(DEAL, filter), start.toString().substring(0, 7), totals[0], totals[2]));
+         rows.add(row(AiLinkBuilder.filteredTableHref(DEAL, filter), start.toString().substring(0, 7), totals[0].toBigIntegerExact(), formatAmount(totals[2])));
       }
       return (table(rows, "Month", "Deals", "Weighted amount (base)"));
    }
@@ -292,7 +322,7 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
       for(QRecord lead : query("crm_form_submission", new QQueryFilter(), "createDate", false, 10))
       {
          String name = (Objects.toString(lead.getValue("firstName"), "") + " " + Objects.toString(lead.getValue("lastName"), "")).trim();
-         if(name.isBlank())
+         if(Objects.toString(lead.getValue("firstName"), "").isBlank() || Objects.toString(lead.getValue("lastName"), "").isBlank())
          {
             name = Objects.toString(lead.getValue("email"), "Web lead");
          }
@@ -339,7 +369,7 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
          BigDecimal target = CrmCurrencyUtils.convertToBaseCurrency(goal.getValueBigDecimal("targetAmount"), goal.getValueString("currencyCode"));
          String attainment = target != null && target.signum() > 0 ? actual.multiply(BigDecimal.valueOf(100)).divide(target, 1, RoundingMode.HALF_UP) + "%" : "No target";
          rows.add(row(AiLinkBuilder.recordHref("crm_sales_goal", goal.getValue("id")),
-            goal.getValueString("userId") + " (" + attainment + ")", target, actual));
+            goal.getValueString("userId") + " (" + attainment + ")", formatAmount(target), formatAmount(actual)));
       }
       TableData data = table(rows, "Owner / attainment", "Target (base)", "Won (base)");
       return (data);
@@ -362,7 +392,7 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
          Serializable user = result.getGroupByValue(owner);
          QQueryFilter ownerFilter = filter.clone().withCriteria(new QFilterCriteria("ownerUserId", user == null ? QCriteriaOperator.IS_BLANK : QCriteriaOperator.EQUALS, user));
          rows.add(row(AiLinkBuilder.filteredTableHref(DEAL, ownerFilter), Objects.toString(user, "Unassigned"),
-            number(result.getAggregateValue(COUNT)), number(result.getAggregateValue(AMOUNT))));
+            number(result.getAggregateValue(COUNT)).toBigIntegerExact(), formatAmount(number(result.getAggregateValue(AMOUNT)))));
       }
       return (table(rows, "Owner", "Won deals", "Won amount (base)"));
    }
@@ -457,6 +487,18 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
    }
 
 
+   /*******************************************************************************
+    ** Group amounts without losing fractional precision or padding whole amounts.
+    *******************************************************************************/
+   static String formatAmount(BigDecimal value)
+   {
+      BigDecimal amount = value == null ? BigDecimal.ZERO : value;
+      DecimalFormat format = new DecimalFormat("#,##0", DecimalFormatSymbols.getInstance(Locale.US));
+      format.setMaximumFractionDigits(Math.max(0, amount.scale()));
+      return (format.format(amount));
+   }
+
+
    /*******************************************************************************
     ** Every cell navigates to its record, or to the records in an aggregate.
     *******************************************************************************/
@@ -489,8 +531,8 @@ public class CrmHomeRenderer extends AbstractWidgetRenderer
     *******************************************************************************/
    static TableData table(List<Map<String, Object>> rows, String first, String second, String third)
    {
-      return (new TableData(null, List.of(new TableData.Column("html", first, "first", "2fr", "left"),
-         new TableData.Column("html", second, "second", "1fr", "left"), new TableData.Column("html", third, "third", "1fr", "left")), rows)
+      return (new TableData(null, List.of(new TableData.Column("html", first, "first", null, "left"),
+         new TableData.Column("html", second, "second", null, "left"), new TableData.Column("html", third, "third", null, "left")), rows)
          .withRowsPerPage(10).withHidePaginationDropdown(true));
    }
 }

src/main/java/com/kingsrook/qbits/crm/widgets/CrmHomeWidgets.java

@@ -37,7 +37,7 @@ import com.kingsrook.qqq.backend.core.model.metadata.dashboard.QWidgetMetaData;
  *******************************************************************************/
 public class CrmHomeWidgets extends MetaDataProducer<MetaDataProducerMultiOutput>
 {
-   public static final List<String> HOME = List.of("crm_today", "crm_pipeline_summary", "crm_deal_forecast", "crm_rotting_deals",
+   public static final List<String> HOME = List.of("crm_today", "crm_setup", "crm_pipeline_summary", "crm_deal_forecast", "crm_rotting_deals",
       "crm_recent_web_leads", "crm_goals", "crm_sales_leaderboard");
    public static final List<String> TODAY = List.of("crm_open_pipeline", "crm_won_month", "crm_new_contacts", "crm_new_web_leads", "crm_overdue_activities");
 
@@ -49,12 +49,12 @@ public class CrmHomeWidgets extends MetaDataProducer<MetaDataProducerMultiOutput
    public MetaDataProducerMultiOutput produce(QInstance instance)
    {
       MetaDataProducerMultiOutput output = new MetaDataProducerMultiOutput();
-      List<String> labels = List.of("Today", "Pipeline by stage", "Forecast", "Needs attention", "Recent web leads", "Goals", "Leaderboard");
+      List<String> labels = List.of("Today", "Setup", "Pipeline by stage", "Forecast", "Needs attention", "Recent web leads", "Goals", "Leaderboard");
       for(int i = 0; i < HOME.size(); i++)
       {
          output.add(widget(HOME.get(i), labels.get(i), i == 0 ? WidgetType.PARENT_WIDGET : WidgetType.TABLE));
       }
-      List<String> statistics = List.of("Open pipeline (base currency)", "Won this month (base currency)", "New contacts (30 days)", "Web leads (7 days)", "My overdue activities");
+      List<String> statistics = List.of("Open pipeline", "Won this month", "New contacts (30 days)", "Web leads (7 days)", "My overdue activities");
       for(int i = 0; i < TODAY.size(); i++)
       {
          output.add(widget(TODAY.get(i), statistics.get(i), WidgetType.STATISTICS));
@@ -76,6 +76,11 @@ public class CrmHomeWidgets extends MetaDataProducer<MetaDataProducerMultiOutput
       {
          widget.getPermissionRules().withCustomPermissionChecker(new QCodeReference(CrmGoalsVisibility.class));
       }
+      if("crm_setup".equals(name))
+      {
+         widget.withPermissionRules(CrmPermissions.hasAccessRules(CrmPermissions.MANAGE_BASE))
+            .getPermissionRules().withCustomPermissionChecker(new QCodeReference(CrmSetupVisibility.class));
+      }
       return (widget);
    }
 }

src/main/java/com/kingsrook/qbits/crm/widgets/CrmSetupStatus.java

@@ -0,0 +1,174 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.widgets;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+
+
+/*******************************************************************************
+ ** The Setup card on the CRM home: the configuration the CRM's processes depend
+ ** on, whether it is in place, and the next step. Reads through core actions, so
+ ** the signed-in user's permissions and tenant locks apply.
+ *******************************************************************************/
+public final class CrmSetupStatus
+{
+   /*******************************************************************************
+    ** OK: in place. TODO: something the CRM needs is missing. OPTIONAL: a feature
+    ** that stays off until it is set up.
+    *******************************************************************************/
+   public enum State
+   {
+      OK("Set up"),
+      TODO("Needs setup"),
+      OPTIONAL("Optional");
+
+      private final String label;
+
+
+
+      /*******************************************************************************
+       ** Constructor.
+       *******************************************************************************/
+      State(String label)
+      {
+         this.label = label;
+      }
+
+
+
+      /*******************************************************************************
+       ** Getter for label.
+       *******************************************************************************/
+      public String getLabel()
+      {
+         return (label);
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** One line of the card.
+    *******************************************************************************/
+   public record Item(String label, String tableName, State state, String detail, String nextStep)
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private CrmSetupStatus()
+   {
+   }
+
+
+
+   /*******************************************************************************
+    ** True when any business setup step still needs attention.
+    *******************************************************************************/
+   public static boolean isIncomplete() throws QException
+   {
+      return (load().stream().anyMatch(item -> item.state() == State.TODO));
+   }
+
+
+
+   /*******************************************************************************
+    ** Build the items for the current user.
+    *******************************************************************************/
+   public static List<Item> load() throws QException
+   {
+      List<Item> items = new ArrayList<>();
+
+      ///////////////////////////////////////////////////////////////////
+      // pipeline and stages: Convert lead needs a default pipeline    //
+      // with at least one stage                                       //
+      ///////////////////////////////////////////////////////////////////
+      List<QRecord> defaults = CrmHomeRenderer.query("crm_pipeline", CrmHomeRenderer.equalsFilter("isDefault", true), "id", true, 1);
+      if(defaults.isEmpty())
+      {
+         items.add(new Item("Default pipeline", "crm_pipeline", State.TODO, "None: Convert lead fails without one.",
+            "Add a pipeline and tick Default (or include the crm-defaults changelog)."));
+         items.add(new Item("Pipeline stages", "crm_pipeline_stage", State.TODO, "A deal needs a pipeline with stages.", "Add its stages once the pipeline exists."));
+      }
+      else
+      {
+         items.add(new Item("Default pipeline", "crm_pipeline", State.OK, defaults.getFirst().getValueString("name") + " is the default.", null));
+         List<QRecord> stages = CrmHomeRenderer.query("crm_pipeline_stage", CrmHomeRenderer.equalsFilter("pipelineId", defaults.getFirst().getValueInteger("id")), "sortOrder", true, 200);
+         boolean won = stages.stream().anyMatch(stage -> Boolean.TRUE.equals(stage.getValueBoolean("isClosedWon")));
+         boolean lost = stages.stream().anyMatch(stage -> Boolean.TRUE.equals(stage.getValueBoolean("isClosedLost")));
+         if(stages.isEmpty())
+         {
+            items.add(new Item("Pipeline stages", "crm_pipeline_stage", State.TODO, "The default pipeline has no stages: Convert lead fails.",
+               "Add its stages, in order, with a win probability each."));
+         }
+         else if(!won || !lost)
+         {
+            items.add(new Item("Pipeline stages", "crm_pipeline_stage", State.TODO, stages.size() + " stage" + (stages.size() == 1 ? "" : "s") + ", but no " + (won ? "Closed Lost" : "Closed Won") + " stage.",
+               "Tick Closed Won and Closed Lost on the stages that end a deal: the home, goals and reports count deals from them."));
+         }
+         else
+         {
+            items.add(new Item("Pipeline stages", "crm_pipeline_stage", State.OK, stages.size() + " stages in the default pipeline.", null));
+         }
+      }
+
+      ////////////////////////////////////////////////////////////////////////
+      // lifecycle stages: the CRM looks up "Lead" and "Opportunity" by name //
+      ////////////////////////////////////////////////////////////////////////
+      List<String> missing = new ArrayList<>();
+      for(String name : List.of("Lead", "Opportunity"))
+      {
+         if(CrmHomeRenderer.query("crm_lifecycle_stage", CrmHomeRenderer.equalsFilter("name", name), "id", true, 1).isEmpty())
+         {
+            missing.add(name);
+         }
+      }
+      if(missing.isEmpty())
+      {
+         items.add(new Item("Lifecycle stages", "crm_lifecycle_stage", State.OK, "Lead and Opportunity exist.", null));
+      }
+      else
+      {
+         String effect = missing.size() == 2 ? "new web leads get no stage and Convert lead does not move the contact"
+            : missing.contains("Lead") ? "new web leads get no stage" : "Convert lead does not move the contact";
+         items.add(new Item("Lifecycle stages", "crm_lifecycle_stage", State.TODO, "Missing " + String.join(" and ", missing) + ": " + effect + ".",
+            "Add " + (missing.size() == 2 ? "stages" : "a stage") + " named exactly " + String.join(" and ", missing.stream().map(name -> "\"" + name + "\"").toList()) + "."));
+      }
+
+      ///////////////////////////////////////////////////////////
+      // currency: amounts need a base currency for the prefix //
+      ///////////////////////////////////////////////////////////
+      List<QRecord> base = CrmHomeRenderer.query("crm_currency", CrmHomeRenderer.equalsFilter("isBaseCurrency", true), "id", true, 1);
+      items.add(base.isEmpty()
+         ? new Item("Base currency", "crm_currency", State.TODO, "None: amounts have no currency prefix and conversions do nothing.", "Add your currency with Base currency ticked and rate 1.")
+         : new Item("Base currency", "crm_currency", State.OK, base.getFirst().getValueString("currencyCode") + " is the base currency.", null));
+
+      return (items);
+   }
+
+}

src/main/java/com/kingsrook/qbits/crm/widgets/CrmSetupVisibility.java

@@ -0,0 +1,64 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package com.kingsrook.qbits.crm.widgets;
+
+
+import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qqq.backend.core.actions.permissions.CustomPermissionChecker;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.AbstractActionInput;
+import com.kingsrook.qqq.backend.core.model.metadata.permissions.MetaDataWithPermissionRules;
+
+
+/*******************************************************************************
+ ** Show the Setup card only to CRM settings holders (crm.manage) and only while
+ ** a business setup step is still missing. Evaluated at request time, so a
+ ** completed setup drops the card from per-session metadata and from render.
+ *******************************************************************************/
+public class CrmSetupVisibility implements CustomPermissionChecker
+{
+   /*******************************************************************************
+    ** Require crm.hasAccess and crm.manage.hasAccess, then an incomplete setup.
+    *******************************************************************************/
+   @Override
+   public void checkPermissionsThrowing(AbstractActionInput input, MetaDataWithPermissionRules metadata) throws QPermissionDeniedException
+   {
+      if(QContext.getQSession() == null || !QContext.getQSession().hasPermission(CrmPermissions.APP_ACCESS) || !QContext.getQSession().hasPermission(CrmPermissions.MANAGE))
+      {
+         throw (new QPermissionDeniedException("CRM settings access is required."));
+      }
+      try
+      {
+         if(CrmSetupStatus.isIncomplete())
+         {
+            return;
+         }
+      }
+      catch(QException e)
+      {
+         throw (new QPermissionDeniedException("Setup status is not available.", e));
+      }
+      throw (new QPermissionDeniedException("CRM setup is complete."));
+   }
+}

src/main/resources/bulkload/crm-profiles.json

@@ -0,0 +1,128 @@
+[
+  {
+    "label": "CRM Contacts - Generic CSV",
+    "tableName": "crm_contact",
+    "mapping": {
+      "version": "1",
+      "layout": "FLAT",
+      "hasHeaderRow": true,
+      "isBulkEdit": false,
+      "fieldList": [
+        {
+          "fieldName": "firstName",
+          "headerName": "First Name",
+          "columnIndex": 0
+        },
+        {
+          "fieldName": "lastName",
+          "headerName": "Last Name",
+          "columnIndex": 1
+        },
+        {
+          "fieldName": "email",
+          "headerName": "Email",
+          "columnIndex": 2
+        },
+        {
+          "fieldName": "phone",
+          "headerName": "Phone",
+          "columnIndex": 3
+        },
+        {
+          "fieldName": "companyId",
+          "headerName": "Company",
+          "columnIndex": 4
+        },
+        {
+          "fieldName": "jobTitle",
+          "headerName": "Job Title",
+          "columnIndex": 5
+        }
+      ]
+    }
+  },
+  {
+    "label": "CRM Companies - Generic CSV",
+    "tableName": "crm_company",
+    "mapping": {
+      "version": "1",
+      "layout": "FLAT",
+      "hasHeaderRow": true,
+      "isBulkEdit": false,
+      "fieldList": [
+        {
+          "fieldName": "name",
+          "headerName": "Company",
+          "columnIndex": 0
+        },
+        {
+          "fieldName": "domain",
+          "headerName": "Domain",
+          "columnIndex": 1
+        },
+        {
+          "fieldName": "phone",
+          "headerName": "Phone",
+          "columnIndex": 2
+        },
+        {
+          "fieldName": "addressLine1",
+          "headerName": "Address",
+          "columnIndex": 3
+        },
+        {
+          "fieldName": "city",
+          "headerName": "City",
+          "columnIndex": 4
+        },
+        {
+          "fieldName": "postalCode",
+          "headerName": "Postal Code",
+          "columnIndex": 5
+        }
+      ]
+    }
+  },
+  {
+    "label": "CRM Deals - Generic CSV",
+    "tableName": "crm_deal",
+    "mapping": {
+      "version": "1",
+      "layout": "FLAT",
+      "hasHeaderRow": true,
+      "isBulkEdit": false,
+      "fieldList": [
+        {
+          "fieldName": "name",
+          "headerName": "Deal",
+          "columnIndex": 0
+        },
+        {
+          "fieldName": "companyId",
+          "headerName": "Company",
+          "columnIndex": 1
+        },
+        {
+          "fieldName": "pipelineId",
+          "headerName": "Pipeline",
+          "columnIndex": 2
+        },
+        {
+          "fieldName": "pipelineStageId",
+          "headerName": "Stage",
+          "columnIndex": 3
+        },
+        {
+          "fieldName": "amount",
+          "headerName": "Amount",
+          "columnIndex": 4
+        },
+        {
+          "fieldName": "currencyCode",
+          "headerName": "Currency",
+          "columnIndex": 5
+        }
+      ]
+    }
+  }
+]

src/main/resources/db/liquibase/qbit-crm/crm-defaults.changelog.sql

@@ -0,0 +1,204 @@
+-- liquibase formatted sql
+-- Copyright 2026 Kingsrook, LLC. Licensed under the Apache License, Version 2.0.
+-- https://www.apache.org/licenses/LICENSE-2.0
+
+-- qbit-crm starter defaults: a CRM that works out of the box.
+-- Include it from the host's master changelog AFTER crm.changelog.sql (or
+-- docs/ddl/postgres.sql) and, on a tenant-enabled install, AFTER
+-- crm-tenancy.changelog.sql too (so the tenant_key check below sees the columns):
+--
+--   - include: { file: db/liquibase/qbit-crm/crm-defaults.changelog.sql }
+--
+-- Without these rows, converting a lead fails ("no default pipeline"), deals
+-- and web leads silently lose their lifecycle stage, and amounts have no
+-- currency prefix.
+--
+-- Rules for this file:
+--   * insert-only and never disruptive: a list is seeded only while its table is
+--     empty (a host that configured its own keeps exactly that), the pipeline
+--     only when no pipeline exists, its stages only when that is the one
+--     pipeline and no stage or deal exists. The lifecycle stages (which change
+--     what intake and Convert lead assign) and the base currency are seeded
+--     only on a fresh install: no contact (respectively no deal) exists yet.
+--     Nothing is ever updated, so an administrator's edits survive;
+--   * every rollback is empty: a rollback must never delete rows the host or a
+--     tenant owns (Liquibase runs rollbacks even for MARK_RAN changesets);
+--   * portable SQL (PostgreSQL and H2): INSERT ... SELECT ... WHERE NOT EXISTS;
+--   * not for tenant-enabled installs: once the crm-tenancy changelog has added
+--     tenant_key to a table, that table's changeset is skipped (MARK_RAN).
+--     Every row of a tenant-locked table needs a tenant key and only the host
+--     knows its tenants, so such a host seeds these same rows once per tenant,
+--     with tenant_key set;
+--   * every changeset checks that its tables exist (SELECT ... WHERE 1 = 0 errors
+--     when one is missing): a host that has not created them yet simply skips it
+--     (MARK_RAN).
+-- CrmDefaultsChangelogTest runs this file twice against a fresh schema.
+
+-- changeset qbit-crm:defaults-1
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_activity_type WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_activity_type' AND LOWER(column_name) = 'tenant_key'
+-- comment: The six activity kinds the CRM logs. Same codes and names CrmStarterData creates on first use, so that stays a no-op.
+INSERT INTO crm_activity_type (code, name, is_system, sort_order, is_active, create_date, modify_date)
+SELECT v.code, v.n, TRUE, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'NOTE' AS code, 'Note' AS n, 0 AS so
+   UNION ALL SELECT 'EMAIL', 'Email', 1
+   UNION ALL SELECT 'CALL', 'Call', 2
+   UNION ALL SELECT 'MEETING', 'Meeting', 3
+   UNION ALL SELECT 'FORM_SUBMISSION', 'Form submission', 4
+   UNION ALL SELECT 'SEQUENCE_STEP', 'Sequence step', 5) v
+WHERE NOT EXISTS (SELECT 1 FROM crm_activity_type x WHERE x.code = v.code OR x.name = v.n);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-2
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_activity_outcome WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_activity_type WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_activity_outcome' AND LOWER(column_name) = 'tenant_key'
+-- comment: Call and meeting outcomes, offered when an activity of that type is logged. Needs the activity types above.
+INSERT INTO crm_activity_outcome (activity_type_id, name, sort_order, is_active, create_date, modify_date)
+SELECT t.id, v.n, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM crm_activity_type t
+JOIN (SELECT 'CALL' AS code, 'Connected' AS n, 1 AS so
+   UNION ALL SELECT 'CALL', 'Left voicemail', 2
+   UNION ALL SELECT 'CALL', 'No answer', 3
+   UNION ALL SELECT 'MEETING', 'Meeting held', 1
+   UNION ALL SELECT 'MEETING', 'Meeting no-show', 2) v ON v.code = t.code
+WHERE NOT EXISTS (SELECT 1 FROM crm_activity_outcome);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-3
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_pipeline WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_pipeline' AND LOWER(column_name) = 'tenant_key'
+-- comment: The default pipeline, only when the host has no pipeline yet. Convert lead refuses to run without a default one.
+INSERT INTO crm_pipeline (name, description, is_default, is_active, create_date, modify_date)
+SELECT 'Sales Pipeline', 'Default sales process for new deals and converted leads.', TRUE, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+WHERE NOT EXISTS (SELECT 1 FROM crm_pipeline);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-4
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_pipeline WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_pipeline_stage WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_pipeline' AND LOWER(column_name) = 'tenant_key'
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_deal WHERE 1 = 0
+-- comment: Stages of Sales Pipeline with their win probability, only when it is the one pipeline, no stage and no deal exists (that is, defaults-3 created it). Closed Won and Closed Lost end a deal.
+INSERT INTO crm_pipeline_stage (pipeline_id, name, sort_order, probability_pct, is_closed_won, is_closed_lost, create_date, modify_date)
+SELECT p.id, v.n, v.so, v.pct, v.won, v.lost, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM crm_pipeline p
+JOIN (SELECT 'Qualification' AS n, 1 AS so, 10 AS pct, FALSE AS won, FALSE AS lost
+   UNION ALL SELECT 'Discovery', 2, 25, FALSE, FALSE
+   UNION ALL SELECT 'Proposal', 3, 50, FALSE, FALSE
+   UNION ALL SELECT 'Negotiation', 4, 75, FALSE, FALSE
+   UNION ALL SELECT 'Closed Won', 5, 100, TRUE, FALSE
+   UNION ALL SELECT 'Closed Lost', 6, 0, FALSE, TRUE) v ON 1 = 1
+WHERE p.name = 'Sales Pipeline'
+   AND NOT EXISTS (SELECT 1 FROM crm_pipeline_stage)
+   AND (SELECT COUNT(*) FROM crm_pipeline) = 1
+   AND NOT EXISTS (SELECT 1 FROM crm_deal);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-5
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_lifecycle_stage WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_lifecycle_stage' AND LOWER(column_name) = 'tenant_key'
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_contact
+-- comment: Lifecycle stages. The CRM looks up Lead (new web leads) and Opportunity (Convert lead) by these exact names.
+INSERT INTO crm_lifecycle_stage (name, sort_order, is_active, description, create_date, modify_date)
+SELECT v.n, v.so, TRUE, v.d, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'Subscriber' AS n, 1 AS so, 'Signed up for updates; not yet a lead.' AS d
+   UNION ALL SELECT 'Lead', 2, 'Showed interest. Web leads start here.'
+   UNION ALL SELECT 'Marketing Qualified Lead', 3, 'Engaged enough for marketing to hand over.'
+   UNION ALL SELECT 'Sales Qualified Lead', 4, 'Accepted by sales as worth pursuing.'
+   UNION ALL SELECT 'Opportunity', 5, 'Has an open deal. Convert lead moves the contact here.'
+   UNION ALL SELECT 'Customer', 6, 'Has bought.'
+   UNION ALL SELECT 'Evangelist', 7, 'A happy customer who refers others.'
+   UNION ALL SELECT 'Other', 8, 'Does not fit the stages above.') v
+WHERE NOT EXISTS (SELECT 1 FROM crm_lifecycle_stage)
+   AND NOT EXISTS (SELECT 1 FROM crm_contact);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-6
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_lead_source WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_lead_source' AND LOWER(column_name) = 'tenant_key'
+-- comment: Where contacts and deals come from. Website is the source the CRM's web forms use.
+INSERT INTO crm_lead_source (name, sort_order, is_active, create_date, modify_date)
+SELECT v.n, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'Website' AS n, 1 AS so
+   UNION ALL SELECT 'Referral', 2
+   UNION ALL SELECT 'Event', 3
+   UNION ALL SELECT 'Email Campaign', 4
+   UNION ALL SELECT 'Social', 5
+   UNION ALL SELECT 'Partner', 6
+   UNION ALL SELECT 'Cold Outreach', 7
+   UNION ALL SELECT 'Other', 8) v
+WHERE NOT EXISTS (SELECT 1 FROM crm_lead_source);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-7
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_industry WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_industry' AND LOWER(column_name) = 'tenant_key'
+-- comment: A short generic industry list for companies.
+INSERT INTO crm_industry (name, sort_order, is_active, create_date, modify_date)
+SELECT v.n, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'Technology' AS n, 1 AS so
+   UNION ALL SELECT 'Healthcare', 2
+   UNION ALL SELECT 'Financial Services', 3
+   UNION ALL SELECT 'Manufacturing', 4
+   UNION ALL SELECT 'Retail', 5
+   UNION ALL SELECT 'Education', 6
+   UNION ALL SELECT 'Real Estate', 7
+   UNION ALL SELECT 'Professional Services', 8
+   UNION ALL SELECT 'Nonprofit', 9
+   UNION ALL SELECT 'Other', 10) v
+WHERE NOT EXISTS (SELECT 1 FROM crm_industry);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-8
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_win_loss_reason WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_win_loss_reason' AND LOWER(column_name) = 'tenant_key'
+-- comment: Why deals are won (type 1) or lost (type 2). Names are unique across both types, so each carries its outcome as a prefix.
+INSERT INTO crm_win_loss_reason (name, type, sort_order, is_active, create_date, modify_date)
+SELECT v.n, v.t, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'Won: Price' AS n, 1 AS t, 1 AS so
+   UNION ALL SELECT 'Won: Product fit', 1, 2
+   UNION ALL SELECT 'Won: Relationship', 1, 3
+   UNION ALL SELECT 'Lost: Price', 2, 4
+   UNION ALL SELECT 'Lost: Competitor', 2, 5
+   UNION ALL SELECT 'Lost: No budget', 2, 6
+   UNION ALL SELECT 'Lost: No decision', 2, 7
+   UNION ALL SELECT 'Lost: Timing', 2, 8) v
+WHERE NOT EXISTS (SELECT 1 FROM crm_win_loss_reason);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-9
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_contact_role WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_contact_role' AND LOWER(column_name) = 'tenant_key'
+-- comment: Roles a contact can play on a deal.
+INSERT INTO crm_contact_role (name, sort_order, is_active, create_date, modify_date)
+SELECT v.n, v.so, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+FROM (SELECT 'Decision Maker' AS n, 1 AS so
+   UNION ALL SELECT 'Champion', 2
+   UNION ALL SELECT 'Influencer', 3
+   UNION ALL SELECT 'Economic Buyer', 4
+   UNION ALL SELECT 'Technical Evaluator', 5
+   UNION ALL SELECT 'End User', 6) v
+WHERE NOT EXISTS (SELECT 1 FROM crm_contact_role);
+-- rollback empty
+
+-- changeset qbit-crm:defaults-10
+-- preconditions onFail:MARK_RAN onError:MARK_RAN
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_currency WHERE 1 = 0
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM information_schema.columns WHERE LOWER(table_name) = 'crm_currency' AND LOWER(column_name) = 'tenant_key'
+-- precondition-sql-check expectedResult:0 SELECT COUNT(*) FROM crm_deal
+-- comment: The base currency, only when none exists: amounts need it for their prefix and conversions. Change it before the first deal if the business does not report in USD.
+INSERT INTO crm_currency (currency_code, name, symbol, exchange_rate_to_base, is_base_currency, is_active, rate_last_updated_date, create_date, modify_date)
+SELECT 'USD', 'US Dollar', '$', 1, TRUE, TRUE, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP
+WHERE NOT EXISTS (SELECT 1 FROM crm_currency WHERE currency_code = 'USD' OR is_base_currency = TRUE)
+   AND NOT EXISTS (SELECT 1 FROM crm_deal);
+-- rollback empty

src/main/resources/db/liquibase/qbit-crm/crm-tenancy.changelog.sql

@@ -0,0 +1,50 @@
+--liquibase formatted sql
+-- Optional: include after crm.changelog.sql ONLY for tenant-enabled installations.
+-- Run with context crm-tenancy. Omit this file entirely when tenancy is off.
+--changeset qbit-crm:020-crm-tenancy context:@crm-tenancy
+ALTER TABLE crm_contact ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_contact_tenant ON crm_contact (tenant_key);
+ALTER TABLE crm_company ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_company_tenant ON crm_company (tenant_key);
+ALTER TABLE crm_deal ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_deal_tenant ON crm_deal (tenant_key);
+ALTER TABLE crm_activity ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_activity_tenant ON crm_activity (tenant_key);
+ALTER TABLE crm_form_submission ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_form_submission_tenant ON crm_form_submission (tenant_key);
+ALTER TABLE crm_email_list ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_email_list_tenant ON crm_email_list (tenant_key);
+ALTER TABLE crm_pipeline ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_pipeline_tenant ON crm_pipeline (tenant_key);
+ALTER TABLE crm_product ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_product_tenant ON crm_product (tenant_key);
+ALTER TABLE crm_email_template ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_email_template_tenant ON crm_email_template (tenant_key);
+ALTER TABLE crm_email_sequence ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_email_sequence_tenant ON crm_email_sequence (tenant_key);
+ALTER TABLE crm_external_mapping ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_external_mapping_tenant ON crm_external_mapping (tenant_key);
+ALTER TABLE crm_lead_score_rule ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_lead_score_rule_tenant ON crm_lead_score_rule (tenant_key);
+ALTER TABLE crm_assignment_rule ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_assignment_rule_tenant ON crm_assignment_rule (tenant_key);
+ALTER TABLE crm_sales_goal ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_sales_goal_tenant ON crm_sales_goal (tenant_key);
+ALTER TABLE crm_currency ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_currency_tenant ON crm_currency (tenant_key);
+ALTER TABLE crm_lifecycle_stage ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_lifecycle_stage_tenant ON crm_lifecycle_stage (tenant_key);
+ALTER TABLE crm_lead_source ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_lead_source_tenant ON crm_lead_source (tenant_key);
+ALTER TABLE crm_industry ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_industry_tenant ON crm_industry (tenant_key);
+ALTER TABLE crm_activity_type ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_activity_type_tenant ON crm_activity_type (tenant_key);
+ALTER TABLE crm_activity_outcome ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_activity_outcome_tenant ON crm_activity_outcome (tenant_key);
+ALTER TABLE crm_contact_role ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_contact_role_tenant ON crm_contact_role (tenant_key);
+ALTER TABLE crm_win_loss_reason ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_win_loss_reason_tenant ON crm_win_loss_reason (tenant_key);
+ALTER TABLE crm_job_state ADD COLUMN tenant_key VARCHAR(250);
+CREATE INDEX idx_crm_job_state_tenant ON crm_job_state (tenant_key);

src/main/resources/db/liquibase/qbit-crm/crm.changelog.sql

@@ -1,12 +1,13 @@
 --liquibase formatted sql
 -- Copyright 2026 Kingsrook, LLC. Licensed under the Apache License, Version 2.0.
 -- https://www.apache.org/licenses/LICENSE-2.0
--- QBit CRM 0.2.0 P1 PostgreSQL reference schema (33 tables).
+-- QBit CRM 0.2.0 P1 PostgreSQL reference schema (34 tables).
 -- QQQ table names equal SQL names; Java field names map to snake_case columns.
 -- Unique constraints match QQQ metadata. Relationship columns are indexed;
 -- foreign-key constraints are deliberately not imposed (the QQQ/host layer owns
 -- validation and deletion policy, including polymorphic and optional references).
--- Optional host-configured securityFields require matching host-managed columns.
+-- Optional tenancy: separately include crm-tenancy.changelog.sql with context crm-tenancy.
+-- With tenancy off, do not include it; this base schema has no tenant_key columns.
 
 --changeset qbit-crm:020-crm_activity
 CREATE TABLE IF NOT EXISTS crm_activity (
@@ -171,27 +172,27 @@ CREATE INDEX IF NOT EXISTS ix_crm_consent_record_contact_id ON crm_consent_recor
 
 --changeset qbit-crm:020-crm_contact
 CREATE TABLE IF NOT EXISTS crm_contact (
-   first_touch_utm_source VARCHAR(250),
-   first_touch_utm_medium VARCHAR(250),
-   first_touch_utm_campaign VARCHAR(250),
-   first_touch_utm_content VARCHAR(250),
-   first_touch_utm_term VARCHAR(250),
+   first_touch_utm_source VARCHAR(500),
+   first_touch_utm_medium VARCHAR(500),
+   first_touch_utm_campaign VARCHAR(500),
+   first_touch_utm_content VARCHAR(500),
+   first_touch_utm_term VARCHAR(500),
    first_touch_landing_page VARCHAR(1000),
    first_touch_referrer VARCHAR(1000),
    first_touch_date TIMESTAMP WITHOUT TIME ZONE,
-   last_touch_utm_source VARCHAR(250),
-   last_touch_utm_medium VARCHAR(250),
-   last_touch_utm_campaign VARCHAR(250),
-   last_touch_utm_content VARCHAR(250),
-   last_touch_utm_term VARCHAR(250),
+   last_touch_utm_source VARCHAR(500),
+   last_touch_utm_medium VARCHAR(500),
+   last_touch_utm_campaign VARCHAR(500),
+   last_touch_utm_content VARCHAR(500),
+   last_touch_utm_term VARCHAR(500),
    last_touch_landing_page VARCHAR(1000),
    last_touch_referrer VARCHAR(1000),
    last_touch_date TIMESTAMP WITHOUT TIME ZONE,
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
-   email VARCHAR(250),
-   secondary_email VARCHAR(250),
+   email VARCHAR(320),
+   secondary_email VARCHAR(320),
    phone VARCHAR(50),
    mobile_phone VARCHAR(50),
    job_title VARCHAR(150),
@@ -199,7 +200,7 @@ CREATE TABLE IF NOT EXISTS crm_contact (
    company_id INTEGER,
    lifecycle_stage_id INTEGER,
    lead_source_id INTEGER,
-   owner_user_id TEXT NOT NULL,
+   owner_user_id TEXT,
    address_line1 VARCHAR(250),
    address_line2 VARCHAR(250),
    city VARCHAR(100),
@@ -265,7 +266,7 @@ CREATE TABLE IF NOT EXISTS crm_deal (
    weighted_amount DECIMAL(20,6),
    company_id INTEGER,
    primary_contact_id INTEGER,
-   owner_user_id TEXT NOT NULL,
+   owner_user_id TEXT,
    lead_source_id INTEGER,
    expected_close_date DATE,
    actual_close_date DATE,
@@ -364,7 +365,7 @@ CREATE TABLE IF NOT EXISTS crm_email_list_member (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    email_list_id INTEGER NOT NULL,
    contact_id INTEGER,
-   email VARCHAR(250) NOT NULL,
+   email VARCHAR(320) NOT NULL,
    first_name VARCHAR(100),
    status INTEGER DEFAULT 1 NOT NULL,
    subscribed_date TIMESTAMP WITHOUT TIME ZONE,
@@ -383,9 +384,13 @@ CREATE INDEX IF NOT EXISTS ix_crm_email_list_member_form_submission_id ON crm_em
 --changeset qbit-crm:020-crm_email_message
 CREATE TABLE IF NOT EXISTS crm_email_message (
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   idempotency_key VARCHAR(250) UNIQUE,
+   email_message_id VARCHAR(100),
+   delivered_date TIMESTAMP WITHOUT TIME ZONE,
+   bounced_date TIMESTAMP WITHOUT TIME ZONE,
    activity_id INTEGER,
    contact_id INTEGER,
-   from_address VARCHAR(250) NOT NULL,
+   from_address VARCHAR(250),
    from_name VARCHAR(100),
    to_addresses TEXT NOT NULL,
    cc_addresses TEXT,
@@ -411,6 +416,7 @@ CREATE TABLE IF NOT EXISTS crm_email_message (
    modify_date TIMESTAMP WITHOUT TIME ZONE
 );
 
+CREATE INDEX IF NOT EXISTS ix_crm_email_message_email_message_id ON crm_email_message (email_message_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_contact_id ON crm_email_message (contact_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_activity_id ON crm_email_message (activity_id);
 CREATE INDEX IF NOT EXISTS ix_crm_email_message_thread_id ON crm_email_message (thread_id);
@@ -478,18 +484,18 @@ CREATE TABLE IF NOT EXISTS crm_form_submission (
    client_hash VARCHAR(64),
    id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    form_type INTEGER NOT NULL,
-   email VARCHAR(250) NOT NULL,
+   email VARCHAR(320) NOT NULL,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    company VARCHAR(250),
    phone VARCHAR(50),
    message TEXT,
    source_url VARCHAR(1000),
-   utm_source VARCHAR(250),
-   utm_medium VARCHAR(250),
-   utm_campaign VARCHAR(250),
-   utm_term VARCHAR(250),
-   utm_content VARCHAR(250),
+   utm_source VARCHAR(500),
+   utm_medium VARCHAR(500),
+   utm_campaign VARCHAR(500),
+   utm_term VARCHAR(500),
+   utm_content VARCHAR(500),
    referrer VARCHAR(1000),
    contact_id INTEGER,
    conversion_status INTEGER DEFAULT 1 NOT NULL,
@@ -674,3 +680,17 @@ CREATE TABLE IF NOT EXISTS crm_win_loss_reason (
 );
 
 CREATE INDEX IF NOT EXISTS ix_crm_consent_record_evidence_form_submission_id ON crm_consent_record (evidence_form_submission_id);
+
+--changeset qbit-crm:crm_job_state
+CREATE TABLE IF NOT EXISTS crm_job_state (
+   id INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+   name VARCHAR(250) NOT NULL UNIQUE,
+   last_success TIMESTAMP WITHOUT TIME ZONE,
+   last_full_pass TIMESTAMP WITHOUT TIME ZONE
+);
+
+--changeset qbit-crm:crm_nullable_intake_names_and_owners
+ALTER TABLE crm_contact ALTER COLUMN first_name DROP NOT NULL;
+ALTER TABLE crm_contact ALTER COLUMN last_name DROP NOT NULL;
+ALTER TABLE crm_contact ALTER COLUMN owner_user_id DROP NOT NULL;
+ALTER TABLE crm_deal ALTER COLUMN owner_user_id DROP NOT NULL;

src/main/resources/qbit-crm.properties

@@ -0,0 +1 @@
+version=${project.version}

src/test/java/com/kingsrook/qbits/crm/CrmAppMetaDataTest.java

@@ -35,7 +35,6 @@ import com.kingsrook.qqq.backend.core.model.metadata.joins.QJoinMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppMetaData;
 import com.kingsrook.qqq.backend.core.model.metadata.layout.QAppSection;
 import com.kingsrook.qqq.backend.core.model.metadata.permissions.PermissionLevel;
-import com.kingsrook.qqq.backend.core.model.metadata.qbits.SourceQBitAware;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QFieldSection;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -70,7 +69,6 @@ class CrmAppMetaDataTest extends BaseTest
       assertThat(app.getWidgets()).containsExactlyElementsOf(CrmHomeWidgets.HOME);
       assertThat(app.getPermissionRules().getPermissionBaseName()).isEqualTo("crm");
       assertThat(app.getPermissionRules().getLevel()).isEqualTo(PermissionLevel.HAS_ACCESS_PERMISSION);
-      assertThat(((SourceQBitAware) app).getSourceQBitName()).isEqualTo("com.kingsrook.qbits:crm");
       assertThat(CrmQBitProducer.produceAppSection().getTables()).containsExactlyElementsOf(CrmAppMetaData.MAIN_TABLES);
       assertThat(QContext.getQInstance().getTable("crm_form_submission").getLabel()).isEqualTo("Web Leads");
       assertThat(QContext.getQInstance().getTable("crm_email_list").getLabel()).isEqualTo("Lists");
@@ -90,7 +88,7 @@ class CrmAppMetaDataTest extends BaseTest
          new CrmQBitProducer().withQBitConfig(new CrmQBitConfig().withDefaultBackendNameForTables(BACKEND_NAME).withAppEnabled(enabled))
             .produce(instance).addSelfToInstance(instance);
          assertThat(instance.getApps()).hasSize(Boolean.FALSE.equals(enabled) ? 0 : 1);
-         assertThat(instance.getTables()).hasSize(33);
+         assertThat(instance.getTables()).hasSize(34);
       }
    }
 
@@ -139,7 +137,7 @@ class CrmAppMetaDataTest extends BaseTest
 
 
    /*******************************************************************************
-    ** No retired trends; all widgets have explicit protection and full width.
+    ** No retired trends; all widgets have explicit protection and statistics use compact widths.
     *******************************************************************************/
    @Test
    void widgets()
@@ -149,7 +147,7 @@ class CrmAppMetaDataTest extends BaseTest
       for(QWidgetMetaDataInterface widget : instance.getWidgets().values())
       {
          assertThat(widget.getPermissionRules()).isNotNull();
-         assertThat(widget.getGridColumns()).isEqualTo(12);
+         assertThat(widget.getGridColumns()).isEqualTo(CrmHomeWidgets.TODAY.contains(widget.getName()) ? 4 : 12);
          assertThat(widget.getType()).isNotEqualTo(WidgetType.HTML.getType());
       }
    }

src/test/java/com/kingsrook/qbits/crm/CrmDataPolicyTest.java

@@ -0,0 +1,163 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.List;
+import java.util.Map;
+import java.util.TreeSet;
+import java.util.regex.Pattern;
+import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qqq.backend.core.actions.ai.AiFieldMetaData;
+import com.kingsrook.qqq.backend.core.actions.ai.DataClassification;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
+import com.kingsrook.qqq.backend.core.model.metadata.security.QSecurityKeyType;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** PII inventory and real tenant isolation through core QueryAction.
+ *******************************************************************************/
+class CrmDataPolicyTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Complete pii inventory.
+    *******************************************************************************/
+   @Test
+   void completePiiInventory()
+   {
+      Map<String, List<String>> expected = Map.of(
+         "crm_contact", List.of("firstName", "lastName", "email", "secondaryEmail", "phone", "mobilePhone", "addressLine1", "addressLine2",
+            "city", "state", "postalCode", "country", "linkedinUrl", "timezone", "jobTitle", "department", "website", "description"),
+         "crm_company", List.of("phone", "addressLine1", "addressLine2", "city", "state", "postalCode", "country"),
+         "crm_form_submission", List.of("firstName", "lastName", "email", "phone", "message", "clientHash", "visitorKey", "consentText", "company"),
+         "crm_email_list_member", List.of("email", "firstName", "consentText", "confirmationTokenHash"),
+         "crm_email_message", List.of("fromAddress", "fromName", "toAddresses", "ccAddresses", "bccAddresses", "subject"),
+         "crm_consent_record", List.of("consentText"), "crm_activity", List.of("description"));
+      TreeSet<String> actual = new TreeSet<>();
+      QContext.getQInstance().getTables().values().forEach(table -> table.getFields().values().forEach(field ->
+      {
+         if(AiFieldMetaData.of(field) != null && AiFieldMetaData.of(field).getClassification() == DataClassification.PII)
+         {
+            actual.add(table.getName() + "." + field.getName());
+         }
+      }));
+      TreeSet<String> inventory = new TreeSet<>();
+      expected.forEach((table, fields) -> fields.forEach(field -> inventory.add(table + "." + field)));
+      assertThat(actual).containsExactlyElementsOf(inventory);
+   }
+
+
+   /*******************************************************************************
+    ** Personal field names cannot lose classification.
+    *******************************************************************************/
+   @Test
+   void personalFieldNamesCannotLoseClassification()
+   {
+      Pattern pattern = Pattern.compile("email|phone|firstName|lastName|address|postal|linkedin", Pattern.CASE_INSENSITIVE);
+      QContext.getQInstance().getTables().values().forEach(table -> table.getFields().values().forEach(field ->
+      {
+         // Foreign-key ids, preference booleans and transport message ids are not personal text.
+         if(field.getType() == QFieldType.STRING && pattern.matcher(field.getName()).find() && !field.getName().equals("emailMessageId"))
+         {
+            assertThat(AiFieldMetaData.of(field)).as(table.getName() + "." + field.getName()).isNotNull();
+            assertThat(AiFieldMetaData.of(field).getClassification()).isEqualTo(DataClassification.PII);
+         }
+      }));
+   }
+
+
+   /*******************************************************************************
+    ** Tenancy off has no fields or locks.
+    *******************************************************************************/
+   @Test
+   void tenancyOffHasNoFieldsOrLocks()
+   {
+      assertThat(new CrmQBitConfig().getTenantSecurityKeyType()).isNull();
+      QContext.getQInstance().getTables().values().forEach(table ->
+      {
+         assertThat(table.getFields().get("tenantKey")).isNull();
+         assertThat(table.getRecordSecurityLocks()).isNullOrEmpty();
+      });
+   }
+
+
+   /*******************************************************************************
+    ** Tenant asees only its contacts deals and joined products.
+    *******************************************************************************/
+   @Test
+   void tenantASeesOnlyItsContactsDealsAndJoinedProducts() throws Exception
+   {
+      QInstance instance = P4TestSupport.host();
+      new CrmQBitProducer().withQBitConfig(new CrmQBitConfig().withDefaultBackendNameForTables(BACKEND_NAME)
+         .withTenantSecurityKeyType("tenant").withTenantAllAccessKeyName("allTenants")).produce(instance).addSelfToInstance(instance);
+      new QInstanceValidator().validate(instance);
+      QContext.init(instance, new QSession().withPermissions(CrmPermissions.ALL).withSecurityKeyValue("tenant", "A"));
+      for(String table : List.of("crm_contact", "crm_deal"))
+      {
+         P4TestSupport.seed(table, new QRecord().withValue("id", 1).withValue("tenantKey", "A"),
+            new QRecord().withValue("id", 2).withValue("tenantKey", "B"), new QRecord().withValue("id", 3));
+      }
+      P4TestSupport.seed("crm_deal_product", new QRecord().withValue("id", 11).withValue("dealId", 1),
+         new QRecord().withValue("id", 22).withValue("dealId", 2));
+      assertThat(ids("crm_contact")).containsExactly(1);
+      assertThat(ids("crm_deal")).containsExactly(1);
+      assertThat(ids("crm_deal_product")).containsExactly(11);
+      QContext.getQSession().withSecurityKeyValue("allTenants", true);
+      assertThat(ids("crm_contact")).contains(1, 2);
+      assertThat(ids("crm_deal")).contains(1, 2);
+      assertThat(ids("crm_deal_product")).containsExactlyInAnyOrder(11, 22);
+      instance.getTables().values().forEach(table -> assertThat(table.getRecordSecurityLocks()).as(table.getName()).isNotEmpty());
+      assertThat(instance.getTable("crm_deal_product").getFields().get("tenantKey")).isNull();
+   }
+
+
+   /*******************************************************************************
+    ** Preserves host key type.
+    *******************************************************************************/
+   @Test
+   void preservesHostKeyType() throws Exception
+   {
+      QInstance instance = P4TestSupport.host();
+      QSecurityKeyType key = new QSecurityKeyType().withName("tenant").withAllAccessKeyName("hostAll");
+      instance.addSecurityKeyType(key);
+      new CrmQBitProducer().withQBitConfig(new CrmQBitConfig().withDefaultBackendNameForTables(BACKEND_NAME)
+         .withTenantSecurityKeyType("tenant").withTenantAllAccessKeyName("ignored")).produce(instance).addSelfToInstance(instance);
+      assertThat(instance.getSecurityKeyType("tenant")).isSameAs(key);
+   }
+
+
+   /*******************************************************************************
+    ** Read through real record locks.
+    *******************************************************************************/
+   private List<Integer> ids(String table) throws Exception
+   {
+      return (new QueryAction().execute(new QueryInput(table)).getRecords().stream().map(row -> row.getValueInteger("id")).toList());
+   }
+}

src/test/java/com/kingsrook/qbits/crm/CrmDefaultsChangelogTest.java

@@ -0,0 +1,517 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.io.InputStream;
+import java.math.BigDecimal;
+import java.nio.charset.StandardCharsets;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.Statement;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import liquibase.Liquibase;
+import liquibase.database.Database;
+import liquibase.database.DatabaseFactory;
+import liquibase.database.jvm.JdbcConnection;
+import liquibase.resource.ClassLoaderResourceAccessor;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The shipped starter defaults (db/liquibase/qbit-crm/crm-defaults.changelog.sql):
+ ** they apply to a fresh schema built from the qbit's own changelog, re-running
+ ** inserts nothing and keeps an administrator's edits, an existing setup is
+ ** respected, and a tenant-enabled schema is left alone.
+ *******************************************************************************/
+public class CrmDefaultsChangelogTest
+{
+   static final String SCHEMA    = "/db/liquibase/qbit-crm/crm.changelog.sql";
+   static final String TENANCY   = "/db/liquibase/qbit-crm/crm-tenancy.changelog.sql";
+   static final String CHANGELOG = "/db/liquibase/qbit-crm/crm-defaults.changelog.sql";
+
+   /*******************************************************************************
+    ** The tables the changelog seeds.
+    *******************************************************************************/
+   public static final List<String> SEEDED_TABLES = List.of("crm_activity_type", "crm_activity_outcome", "crm_pipeline", "crm_pipeline_stage",
+      "crm_lifecycle_stage", "crm_lead_source", "crm_industry", "crm_win_loss_reason", "crm_contact_role", "crm_currency");
+
+
+
+   /*******************************************************************************
+    ** Fresh schema, seed twice (ignoring preconditions, so the SQL guards
+    ** themselves are tested): same rows; an edit survives.
+    *******************************************************************************/
+   @Test
+   void seedsAFreshSchemaInsertOnly() throws Exception
+   {
+      try(Connection connection = freshSchema())
+      {
+         runChangelog(connection, true);
+         Map<String, Integer> first = counts(connection);
+         assertThat(first).containsEntry("crm_activity_type", 6).containsEntry("crm_activity_outcome", 5).containsEntry("crm_pipeline", 1)
+            .containsEntry("crm_pipeline_stage", 6).containsEntry("crm_lifecycle_stage", 8).containsEntry("crm_lead_source", 8)
+            .containsEntry("crm_win_loss_reason", 8).containsEntry("crm_contact_role", 6).containsEntry("crm_currency", 1);
+         assertThat(first.get("crm_industry")).isEqualTo(10);
+
+         try(Statement statement = connection.createStatement())
+         {
+            statement.execute("UPDATE crm_pipeline_stage SET probability_pct = 15 WHERE name = 'Qualification'");
+            statement.execute("UPDATE crm_currency SET name = 'Dollar' WHERE currency_code = 'USD'");
+         }
+
+         runChangelog(connection, true);
+         assertThat(counts(connection)).isEqualTo(first);
+         assertThat(scalar(connection, "SELECT probability_pct FROM crm_pipeline_stage WHERE name = 'Qualification'")).isEqualTo("15");
+         assertThat(scalar(connection, "SELECT name FROM crm_currency WHERE currency_code = 'USD'")).isEqualTo("Dollar");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The seeded rows are what the CRM's code looks up and relies on.
+    *******************************************************************************/
+   @Test
+   void seededRowsMatchWhatTheCodeNeeds() throws Exception
+   {
+      try(Connection connection = freshSchema())
+      {
+         runChangelog(connection, false);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline WHERE is_default = TRUE")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage s JOIN crm_pipeline p ON p.id = s.pipeline_id WHERE p.is_default = TRUE")).isEqualTo("6");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage WHERE is_closed_won = TRUE AND probability_pct = 100 AND name = 'Closed Won'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage WHERE is_closed_lost = TRUE AND probability_pct = 0 AND name = 'Closed Lost'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lifecycle_stage WHERE name IN ('Lead', 'Opportunity')")).isEqualTo("2");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lead_source WHERE name = 'Website'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT exchange_rate_to_base FROM crm_currency WHERE is_base_currency = TRUE AND currency_code = 'USD'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_win_loss_reason WHERE type = 1")).isEqualTo("3");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_win_loss_reason WHERE type = 2")).isEqualTo("5");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_activity_outcome o JOIN crm_activity_type t ON t.id = o.activity_type_id WHERE t.code = 'CALL'")).isEqualTo("3");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_activity_outcome o JOIN crm_activity_type t ON t.id = o.activity_type_id WHERE t.code = 'MEETING'")).isEqualTo("2");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A host that already has its own pipeline or base currency keeps it: the
+    ** default pipeline is not added, and a second base currency never appears.
+    *******************************************************************************/
+   @Test
+   void keepsAnExistingSetup() throws Exception
+   {
+      try(Connection connection = freshSchema(); Statement statement = connection.createStatement())
+      {
+         statement.execute("INSERT INTO crm_pipeline (name, is_default, is_active) VALUES ('Mine', TRUE, TRUE)");
+         statement.execute("INSERT INTO crm_currency (currency_code, name, is_base_currency) VALUES ('EUR', 'Euro', TRUE)");
+         runChangelog(connection, true);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage")).isEqualTo("0");
+         assertThat(scalar(connection, "SELECT currency_code FROM crm_currency")).isEqualTo("EUR");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_currency")).isEqualTo("1");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The real thing: Liquibase applies the schema and then the defaults on H2;
+    ** a second update runs nothing; the rows are what the SQL-level tests saw.
+    *******************************************************************************/
+   @Test
+   void liquibaseAppliesTheDefaultsOnce() throws Exception
+   {
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, SCHEMA);
+         liquibase(connection, CHANGELOG);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM databasechangelog WHERE filename LIKE '%crm-defaults%' AND exectype = 'EXECUTED'")).isEqualTo("10");
+         Map<String, Integer> first = counts(connection);
+         assertThat(first).containsEntry("crm_pipeline", 1).containsEntry("crm_pipeline_stage", 6).containsEntry("crm_lifecycle_stage", 8);
+
+         connection.createStatement().execute("UPDATE crm_pipeline_stage SET probability_pct = 15 WHERE name = 'Qualification'");
+         liquibase(connection, CHANGELOG);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM databasechangelog WHERE filename LIKE '%crm-defaults%'")).isEqualTo("10");
+         assertThat(counts(connection)).isEqualTo(first);
+         assertThat(scalar(connection, "SELECT probability_pct FROM crm_pipeline_stage WHERE name = 'Qualification'")).isEqualTo("15");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A host that has not created the CRM tables yet does not fail: every
+    ** changeset is marked ran. A tenant-enabled schema is marked ran too.
+    *******************************************************************************/
+   @Test
+   void liquibaseMarksRanWhenTablesAreMissingOrTenanted() throws Exception
+   {
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, CHANGELOG);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM databasechangelog WHERE exectype = 'MARK_RAN'")).isEqualTo("10");
+      }
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, SCHEMA);
+         liquibase(connection, TENANCY);
+         liquibase(connection, CHANGELOG);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM databasechangelog WHERE filename LIKE '%crm-defaults%' AND exectype = 'MARK_RAN'")).isEqualTo("10");
+         for(String table : SEEDED_TABLES)
+         {
+            assertThat(scalar(connection, "SELECT COUNT(*) FROM " + table)).as(table).isEqualTo("0");
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Rolling the defaults back deletes nothing: host-owned rows (and tenant rows,
+    ** whose changesets were marked ran) survive a Liquibase rollback.
+    *******************************************************************************/
+   @Test
+   void rollbackNeverDeletesHostRows() throws Exception
+   {
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, SCHEMA);
+         liquibase(connection, CHANGELOG);
+         Map<String, Integer> seeded = counts(connection);
+         connection.createStatement().execute("INSERT INTO crm_lead_source (name, sort_order) VALUES ('Host source', 99)");
+         connection.createStatement().execute("INSERT INTO crm_pipeline (name, is_default) VALUES ('Host pipeline', FALSE)");
+         connection.commit();
+         rollback(connection, CHANGELOG, 10);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lead_source WHERE name = 'Host source'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline WHERE name = 'Host pipeline'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lead_source")).isEqualTo("9");
+         assertThat(seeded.get("crm_pipeline_stage")).isEqualTo(6);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage")).isEqualTo("6");
+      }
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, SCHEMA);
+         liquibase(connection, TENANCY);
+         liquibase(connection, CHANGELOG);
+         connection.createStatement().execute("INSERT INTO crm_pipeline (name, is_default, tenant_key) VALUES ('Sales Pipeline', TRUE, 'acme')");
+         connection.createStatement().execute("INSERT INTO crm_lifecycle_stage (name, sort_order, tenant_key) VALUES ('Lead', 1, 'acme')");
+         connection.commit();
+         rollback(connection, CHANGELOG, 10);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline WHERE tenant_key = 'acme'")).isEqualTo("1");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lifecycle_stage WHERE tenant_key = 'acme'")).isEqualTo("1");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Lifecycle stages and the base currency change what intake, Convert lead
+    ** and amounts do, so they are seeded only on a fresh install; the pipeline
+    ** stages only into the pipeline the defaults created.
+    *******************************************************************************/
+   @Test
+   void behaviorChangingSeedsNeedAFreshInstall() throws Exception
+   {
+      try(Connection connection = freshSchema())
+      {
+         connection.createStatement().execute("INSERT INTO crm_contact (email) VALUES ('a@example.test')");
+         runChangelog(connection, false);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lifecycle_stage")).isEqualTo("0");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lead_source")).isEqualTo("8");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_currency")).isEqualTo("1");
+      }
+      try(Connection connection = freshSchema())
+      {
+         connection.createStatement().execute("INSERT INTO crm_deal (name, pipeline_id, pipeline_stage_id) VALUES ('d', 1, 1)");
+         runChangelog(connection, false);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_currency")).isEqualTo("0");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage")).isEqualTo("0");
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_lifecycle_stage")).isEqualTo("8");
+      }
+      try(Connection connection = freshSchema())
+      {
+         connection.createStatement().execute("INSERT INTO crm_pipeline (name, is_default) VALUES ('Sales Pipeline', TRUE)");
+         connection.createStatement().execute("INSERT INTO crm_pipeline (name, is_default) VALUES ('Other', FALSE)");
+         runChangelog(connection, false);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline_stage")).as("not the only pipeline").isEqualTo("0");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Order matters: included before crm-tenancy, the untenanted rows are seeded
+    ** and the tenancy columns are added afterwards; included after, nothing is.
+    *******************************************************************************/
+   @Test
+   void orderAgainstTenancyMatters() throws Exception
+   {
+      try(Connection connection = DriverManager.getConnection(url()))
+      {
+         liquibase(connection, SCHEMA);
+         liquibase(connection, CHANGELOG);
+         liquibase(connection, TENANCY);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline WHERE tenant_key IS NULL")).as("wrong order: untenanted rows").isEqualTo("1");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static void rollback(Connection connection, String path, int count) throws Exception
+   {
+      Database database = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(new JdbcConnection(connection));
+      new Liquibase(path.substring(1), new ClassLoaderResourceAccessor(), database).rollback(count, "crm-tenancy");
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String url()
+   {
+      return ("jdbc:h2:mem:crmlb" + System.nanoTime() + ";MODE=PostgreSQL;DEFAULT_NULL_ORDERING=HIGH");
+   }
+
+
+
+   /*******************************************************************************
+    ** Apply one changelog (resource path with a leading slash) through Liquibase.
+    *******************************************************************************/
+   private static void liquibase(Connection connection, String path) throws Exception
+   {
+      Database database = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(new JdbcConnection(connection));
+      new Liquibase(path.substring(1), new ClassLoaderResourceAccessor(), database).update("crm-tenancy");
+   }
+
+
+
+   /*******************************************************************************
+    ** A tenant-enabled schema (tenant_key columns added) is skipped, honoring each
+    ** changeset's precondition: seeding without a tenant key would create rows no
+    ** tenant can see. A plain schema is not skipped.
+    *******************************************************************************/
+   @Test
+   void skipsTenantEnabledTables() throws Exception
+   {
+      try(Connection connection = freshSchema(); Statement statement = connection.createStatement())
+      {
+         for(String sql : statements(resource(TENANCY)))
+         {
+            statement.execute(sql);
+         }
+         runChangelog(connection, false);
+         for(String table : SEEDED_TABLES)
+         {
+            assertThat(scalar(connection, "SELECT COUNT(*) FROM " + table)).as(table).isEqualTo("0");
+         }
+      }
+      try(Connection connection = freshSchema())
+      {
+         runChangelog(connection, false);
+         assertThat(scalar(connection, "SELECT COUNT(*) FROM crm_pipeline")).isEqualTo("1");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Every changeset guards itself: a precondition (a host without the table
+    ** marks it ran), an insert that skips rows that exist, and a rollback.
+    *******************************************************************************/
+   @Test
+   void everyChangesetIsGuarded() throws Exception
+   {
+      List<String> changesets = changesets(resource(CHANGELOG));
+      assertThat(changesets).hasSizeGreaterThanOrEqualTo(SEEDED_TABLES.size());
+      for(String changeset : changesets)
+      {
+         assertThat(changeset).contains("-- preconditions onFail:MARK_RAN onError:MARK_RAN").contains("-- rollback ").contains("NOT EXISTS")
+            .contains("-- precondition-sql-check expectedResult:0 ").doesNotContain("UPDATE ");
+      }
+      for(String table : SEEDED_TABLES)
+      {
+         assertThat(resource(CHANGELOG)).contains("INSERT INTO " + table + " ");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** A fresh H2 (PostgreSQL mode) with the qbit's own schema.
+    *******************************************************************************/
+   public static Connection freshSchema() throws Exception
+   {
+      Connection connection = DriverManager.getConnection("jdbc:h2:mem:crmdefaults" + System.nanoTime() + ";MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;DEFAULT_NULL_ORDERING=HIGH");
+      try(Statement statement = connection.createStatement())
+      {
+         for(String sql : statements(resource(SCHEMA)))
+         {
+            statement.execute(sql);
+         }
+      }
+      return (connection);
+   }
+
+
+
+   /*******************************************************************************
+    ** Run each changeset's statements. With ignorePreconditions, the SQL runs
+    ** whatever the preconditions say; otherwise a changeset whose
+    ** precondition-sql-check does not give its expected result is skipped, as
+    ** Liquibase would (MARK_RAN).
+    *******************************************************************************/
+   public static void runChangelog(Connection connection, boolean ignorePreconditions) throws Exception
+   {
+      try(Statement statement = connection.createStatement())
+      {
+         for(String changeset : changesets(resource(CHANGELOG)))
+         {
+            if(!ignorePreconditions && !preconditionsHold(connection, changeset))
+            {
+               continue;
+            }
+            for(String sql : statements(changeset))
+            {
+               statement.execute(sql);
+            }
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static boolean preconditionsHold(Connection connection, String changeset) throws Exception
+   {
+      Matcher m = Pattern.compile("(?m)^-- precondition-sql-check expectedResult:(\\d+) (.*)$").matcher(changeset);
+      while(m.find())
+      {
+         if(!scalar(connection, m.group(2)).equals(m.group(1)))
+         {
+            return (false);
+         }
+      }
+      return (true);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String resource(String path) throws Exception
+   {
+      try(InputStream stream = CrmDefaultsChangelogTest.class.getResourceAsStream(path))
+      {
+         assertThat(stream).as(path + " is on the classpath").isNotNull();
+         return (new String(stream.readAllBytes(), StandardCharsets.UTF_8));
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** The text of each changeset (from its "-- changeset" line).
+    *******************************************************************************/
+   static List<String> changesets(String changelog)
+   {
+      List<String> rs = new ArrayList<>();
+      for(String part : changelog.split("(?m)^(?=-- changeset )"))
+      {
+         if(part.startsWith("-- changeset "))
+         {
+            rs.add(part);
+         }
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    ** SQL statements, without comment lines, split at a ';' that ends a line.
+    *******************************************************************************/
+   static List<String> statements(String sql)
+   {
+      StringBuilder text = new StringBuilder();
+      for(String line : sql.split("\\R"))
+      {
+         if(!line.strip().startsWith("--"))
+         {
+            text.append(line).append("\n");
+         }
+      }
+      List<String> rs = new ArrayList<>();
+      for(String statement : text.toString().split(";\\s*\\n"))
+      {
+         if(!statement.isBlank())
+         {
+            rs.add(statement.strip().replaceAll(";$", ""));
+         }
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static Map<String, Integer> counts(Connection connection) throws Exception
+   {
+      Map<String, Integer> rs = new LinkedHashMap<>();
+      for(String table : SEEDED_TABLES)
+      {
+         rs.put(table, Integer.valueOf(scalar(connection, "SELECT COUNT(*) FROM " + table)));
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   static String scalar(Connection connection, String sql) throws Exception
+   {
+      try(Statement statement = connection.createStatement(); ResultSet rs = statement.executeQuery(sql))
+      {
+         rs.next();
+         Object value = rs.getObject(1);
+         return (value instanceof BigDecimal bd ? bd.stripTrailingZeros().toPlainString() : String.valueOf(value));
+      }
+   }
+
+}

src/test/java/com/kingsrook/qbits/crm/CrmHealthBulkLoadTest.java

@@ -0,0 +1,231 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.time.Instant;
+import java.time.temporal.ChronoUnit;
+import java.util.List;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.bulkload.CrmBulkLoadProfiles;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.health.CrmHealthChecks;
+import com.kingsrook.qbits.crm.scoring.processes.CalculateLeadScoresProcess;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.health.HealthCheckInput;
+import com.kingsrook.qqq.backend.core.health.HealthCheckMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthChecksMetaData;
+import com.kingsrook.qqq.backend.core.health.HealthStatus;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.savedbulkloadprofiles.SavedBulkLoadProfileMetaDataProvider;
+import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
+import com.kingsrook.qqq.backend.core.processes.implementations.bulk.insert.model.BulkLoadProfile;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Maintenance health thresholds and host-owned bulk-load profile seeding.
+ *******************************************************************************/
+class CrmHealthBulkLoadTest extends BaseTest
+{
+   /*******************************************************************************
+    ** No transport or score run needs attention; the producer registered the
+    ** same checks with the core health registry.
+    *******************************************************************************/
+   @Test
+   void noTransportOrScoreRunNeedsAttention() throws Exception
+   {
+      var checks = new CrmHealthChecks(new CrmQBitConfig());
+      var results = checks.run();
+      assertThat(results.get(CrmHealthChecks.EMAIL).getStatus()).isEqualTo(HealthStatus.DEGRADED);
+      assertThat(results.get(CrmHealthChecks.LEAD_SCORE).getStatus()).isEqualTo(HealthStatus.DEGRADED);
+      assertThat(results.get(CrmHealthChecks.SEQUENCE_LAG).getStatus()).isEqualTo(HealthStatus.UP);
+      for(HealthCheckMetaData registered : crmChecks(QContext.getQInstance()))
+      {
+         assertThat(registered.getCheckInstance().run(new HealthCheckInput()).getStatus()).isEqualTo(results.get(registered.getName()).getStatus());
+      }
+   }
+
+
+   /*******************************************************************************
+    ** The producer registers exactly the three CRM checks as valid core
+    ** definitions, and re-registration does not duplicate them.
+    *******************************************************************************/
+   @Test
+   void producerRegistersCoreHealthChecks()
+   {
+      QInstance instance = QContext.getQInstance();
+      assertThat(crmChecks(instance)).extracting(HealthCheckMetaData::getName)
+         .containsExactlyInAnyOrder(CrmHealthChecks.EMAIL, CrmHealthChecks.SEQUENCE_LAG, CrmHealthChecks.LEAD_SCORE);
+      assertThat(crmChecks(instance)).allSatisfy(check ->
+      {
+         assertThat(check.getCheckInstance()).isNotNull();
+         assertThat(check.getTimeoutMs()).isLessThan(check.getIntervalSeconds() * 1000);
+      });
+      CrmHealthChecks.register(instance, new CrmQBitConfig());
+      assertThat(crmChecks(instance)).hasSize(3);
+   }
+
+
+   /*******************************************************************************
+    ** Healthy then late jobs.
+    *******************************************************************************/
+   @Test
+   void healthyThenLateJobs() throws Exception
+   {
+      CrmEmailTransport transport = new CrmEmailTransport(new CrmQBitConfig())
+      {
+         @Override
+         public CrmReadiness readiness()
+         {
+            return (CrmReadiness.CORE_MESSAGING);
+         }
+      };
+      CrmHealthChecks checks = new CrmHealthChecks(transport);
+      P4TestSupport.seed("crm_job_state", new QRecord().withValue("id", 1).withValue("name", CalculateLeadScoresProcess.NAME)
+         .withValue("lastSuccess", Instant.now().minus(2, ChronoUnit.HOURS)));
+      P4TestSupport.seed("crm_sequence_enrollment", new QRecord().withValue("id", 1).withValue("status", CrmEnrollmentStatus.ACTIVE.getId())
+         .withValue("nextStepDate", Instant.now().minus(29, ChronoUnit.MINUTES)),
+         new QRecord().withValue("id", 2).withValue("status", CrmEnrollmentStatus.UNENROLLED.getId())
+            .withValue("nextStepDate", Instant.now().minus(2, ChronoUnit.DAYS)));
+      assertThat(checks.run().values()).allMatch(result -> result.getStatus() == HealthStatus.UP);
+      com.kingsrook.qbits.crm.core.CrmRecords.update("crm_job_state", new QRecord().withValue("id", 1)
+         .withValue("lastSuccess", Instant.now().minus(181, ChronoUnit.MINUTES)));
+      com.kingsrook.qbits.crm.core.CrmRecords.update("crm_sequence_enrollment", new QRecord().withValue("id", 1)
+         .withValue("nextStepDate", Instant.now().minus(31, ChronoUnit.MINUTES)));
+      assertThat(checks.run().get(CrmHealthChecks.SEQUENCE_LAG).getStatus()).isEqualTo(HealthStatus.DEGRADED);
+      assertThat(checks.run().get(CrmHealthChecks.LEAD_SCORE).getStatus()).isEqualTo(HealthStatus.DEGRADED);
+   }
+
+
+   /*******************************************************************************
+    ** Health failure reports unknown.
+    *******************************************************************************/
+   @Test
+   void healthFailureReportsUnknown() throws Exception
+   {
+      CrmHealthChecks checks = new CrmHealthChecks(new CrmEmailTransport(new CrmQBitConfig())
+      {
+         @Override
+         public CrmReadiness readiness()
+         {
+            throw (new IllegalStateException("unavailable"));
+         }
+      });
+      assertThat(checks.check(CrmHealthChecks.EMAIL).run(new HealthCheckInput()).getStatus()).isEqualTo(HealthStatus.UNKNOWN);
+   }
+
+
+   /*******************************************************************************
+    ** Profiles are optional idempotent and valid core mappings.
+    *******************************************************************************/
+   @Test
+   void profilesAreOptionalIdempotentAndValidCoreMappings() throws Exception
+   {
+      CrmBulkLoadProfiles.ensure();
+      assertThat(QContext.getQInstance().getTable("savedBulkLoadProfile")).isNull();
+      var table = new SavedBulkLoadProfileMetaDataProvider().defineSavedBulkLoadProfileTable(BACKEND_NAME, ignored ->
+      {
+         // Host has no additional backend details.
+      });
+      QContext.getQInstance().addTable(table);
+      CrmBulkLoadProfiles.ensure();
+      CrmBulkLoadProfiles.ensure();
+      var rows = new QueryAction().execute(new QueryInput("savedBulkLoadProfile")).getRecords();
+      assertThat(rows).hasSize(3);
+      for(QRecord row : rows)
+      {
+         BulkLoadProfile profile = new ObjectMapper().readValue(row.getValueString("mappingJson"), BulkLoadProfile.class);
+         assertThat(profile.getHasHeaderRow()).isTrue();
+         assertThat(profile.getLayout()).isEqualTo("FLAT");
+         assertThat(profile.getFieldList()).isNotEmpty();
+         profile.getFieldList().forEach(field -> assertThat(QContext.getQInstance().getTable(row.getValueString("tableName")).getField(field.getFieldName())).isNotNull());
+         if(row.getValueString("tableName").equals("crm_contact"))
+         {
+            assertThat(profile.getFieldList().stream().map(field -> field.getHeaderName())).containsExactlyElementsOf(
+               List.of("First Name", "Last Name", "Email", "Phone", "Company", "Job Title"));
+         }
+      }
+      QRecord first = rows.getFirst();
+      com.kingsrook.qbits.crm.core.CrmRecords.update("savedBulkLoadProfile", new QRecord().withValue("id", first.getValue("id"))
+         .withValue("mappingJson", "{\"hostEdited\":true}"));
+      CrmBulkLoadProfiles.ensure();
+      assertThat(com.kingsrook.qqq.backend.core.actions.tables.GetAction.execute("savedBulkLoadProfile", first.getValue("id"))
+         .getValueString("mappingJson")).contains("hostEdited");
+   }
+
+   /*******************************************************************************
+    ** The core HealthRunner runs each check on a worker thread with no caller
+    ** QContext, as a QSystemUserSession. A registered CRM check must succeed that
+    ** way on a host whose authentication rejects tokenless sessions (OAuth2, Auth0).
+    *******************************************************************************/
+   @Test
+   void registeredChecksRunAsCoreSystemUserOnTokenRequiredHost() throws Exception
+   {
+      var instance = QContext.getQInstance();
+      instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData()
+         .withName("token-required")
+         .withType(QAuthenticationType.MOCK)
+         .withModuleCodeReference(new QCodeReference(TokenRequiredAuthenticationModule.class)));
+      HealthCheckMetaData sequenceLag = crmChecks(instance).stream()
+         .filter(check -> CrmHealthChecks.SEQUENCE_LAG.equals(check.getName())).findFirst().orElseThrow();
+      var status = java.util.concurrent.CompletableFuture.supplyAsync(() ->
+      {
+         assertThat(QContext.getQInstance()).isNull();
+         QContext.init(instance, new QSystemUserSession(instance));
+         try
+         {
+            return (sequenceLag.getCheckInstance().run(new HealthCheckInput().withQInstance(instance)).getStatus());
+         }
+         catch(Exception e)
+         {
+            throw (new AssertionError(e));
+         }
+         finally
+         {
+            QContext.clear();
+         }
+      }).get();
+      assertThat(status).isEqualTo(HealthStatus.UP);
+      assertThat(QContext.getQInstance()).isSameAs(instance);
+   }
+
+
+
+   /*******************************************************************************
+    ** The CRM definitions in the core health registry.
+    *******************************************************************************/
+   private static List<HealthCheckMetaData> crmChecks(QInstance instance)
+   {
+      return (HealthChecksMetaData.ofOrWithNew(instance).getChecks().stream()
+         .filter(check -> "crm".equals(check.getComponent())).toList());
+   }
+
+}

src/test/java/com/kingsrook/qbits/crm/CrmPersonalDataTest.java

@@ -0,0 +1,143 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEntityType;
+import com.kingsrook.qbits.crm.privacy.CrmPersonalData;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.audits.AuditsMetaDataProvider;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Seed all CRM copies and audit copies; verify no original personal strings survive.
+ *******************************************************************************/
+class CrmPersonalDataTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Erasure covers all copies including audit values and messages.
+    *******************************************************************************/
+   @Test
+   void erasureCoversAllCopiesIncludingAuditValuesAndMessages() throws Exception
+   {
+      new AuditsMetaDataProvider().defineStandardAuditTables(QContext.getQInstance(), BACKEND_NAME, ignored ->
+      {
+         // Host has no additional backend details.
+      });
+      List<String> originals = new ArrayList<>();
+      QRecord contact = personal(new QRecord().withValue("id", 1), originals, "firstName", "lastName", "email", "secondaryEmail", "phone", "mobilePhone",
+         "addressLine1", "addressLine2", "city", "state", "postalCode", "country", "timezone", "jobTitle", "department", "website", "linkedinUrl", "description");
+      P4TestSupport.seed("crm_contact", contact);
+      P4TestSupport.seed("crm_form_submission", personal(new QRecord().withValue("id", 1).withValue("contactId", 1), originals,
+         "firstName", "lastName", "email", "phone", "message", "clientHash", "visitorKey", "consentText"),
+         personal(new QRecord().withValue("id", 2), originals, "firstName", "lastName", "phone", "message", "clientHash", "visitorKey")
+            .withValue("email", contact.getValue("email")));
+      P4TestSupport.seed("crm_email_list_member", personal(new QRecord().withValue("id", 1).withValue("contactId", 1), originals,
+         "email", "firstName", "confirmationTokenHash", "consentText"));
+      P4TestSupport.seed("crm_activity", personal(new QRecord().withValue("id", 1).withValue("contactId", 1), originals, "description", "subject"));
+      P4TestSupport.seed("crm_email_message", personal(new QRecord().withValue("id", 1).withValue("contactId", 1), originals,
+         "fromAddress", "fromName", "toAddresses", "ccAddresses", "bccAddresses", "subject", "bodyHtml", "bodyText"),
+         personal(new QRecord().withValue("id", 2).withValue("activityId", 1), originals, "fromAddress", "toAddresses", "subject"));
+      P4TestSupport.seed("crm_consent_record", personal(new QRecord().withValue("id", 1).withValue("contactId", 1)
+         .withValue("consentType", CrmConsentType.EMAIL.getId()).withValue("status", CrmConsentStatus.GRANTED.getId()), originals, "consentText"));
+      P4TestSupport.seed("crm_external_mapping", personal(new QRecord().withValue("id", 1).withValue("entityId", 1)
+         .withValue("entityType", CrmEntityType.CONTACT.getId()), originals, "externalId"));
+      P4TestSupport.seed("crm_sequence_enrollment", new QRecord().withValue("id", 1).withValue("contactId", 1)
+         .withValue("status", CrmEnrollmentStatus.ACTIVE.getId()).withValue("nextStepDate", Instant.now()));
+      int id = 1;
+      for(String table : List.of("crm_contact", "crm_form_submission", "crm_email_list_member", "crm_activity", "crm_email_message",
+         "crm_consent_record", "crm_external_mapping", "crm_sequence_enrollment"))
+      {
+         P4TestSupport.seed("auditTable", new QRecord().withValue("id", id).withValue("name", table));
+         P4TestSupport.seed("audit", personal(new QRecord().withValue("id", (long) id).withValue("auditTableId", id).withValue("recordId", 1), originals, "message"));
+         P4TestSupport.seed("auditDetail", personal(new QRecord().withValue("id", (long) id).withValue("auditId", (long) id), originals,
+            "oldValue", "newValue", "message"));
+         id++;
+      }
+      CrmPersonalData.erase(1);
+      for(var table : QContext.getQInstance().getTables().values())
+      {
+         for(QRecord row : new QueryAction().execute(new QueryInput(table.getName())).getRecords())
+         {
+            for(Object value : row.getValues().values())
+            {
+               if(value instanceof String text)
+               {
+                  originals.forEach(original -> assertThat(text).as(table.getName() + ":" + row.getValue("id")).doesNotContain(original));
+               }
+            }
+         }
+      }
+      assertThat(new QueryAction().execute(new QueryInput("crm_external_mapping")).getRecords()).isEmpty();
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("status")).isEqualTo(CrmEnrollmentStatus.UNENROLLED.getId());
+      var consents = new QueryAction().execute(new QueryInput("crm_consent_record")).getRecords();
+      assertThat(consents).hasSize(2);
+      assertThat(consents).anySatisfy(row ->
+      {
+         assertThat(row.getValueInteger("status")).isEqualTo(CrmConsentStatus.WITHDRAWN.getId());
+         assertThat(row.getValueInteger("consentType")).isEqualTo(CrmConsentType.DATA_PROCESSING.getId());
+         assertThat(row.getValueString("consentText")).startsWith("Erased on ");
+      });
+   }
+
+
+   /*******************************************************************************
+    ** Missing contact fails and ordinary consent editing stays forbidden.
+    *******************************************************************************/
+   @Test
+   void missingContactFailsAndOrdinaryConsentEditingStaysForbidden() throws Exception
+   {
+      assertThatThrownBy(() -> CrmPersonalData.erase(999)).hasMessageContaining("not found");
+      P4TestSupport.seed("crm_consent_record", new QRecord().withValue("id", 1).withValue("contactId", 1).withValue("consentText", "original"));
+      assertThatThrownBy(() -> new UpdateAction().execute(new UpdateInput("crm_consent_record")
+         .withRecord(new QRecord().withValue("id", 1).withValue("consentText", "erased")))).hasMessageContaining("cannot be modified");
+   }
+
+
+   /*******************************************************************************
+    ** Distinct sentinels make missing field coverage visible without false matches.
+    *******************************************************************************/
+   private QRecord personal(QRecord record, List<String> originals, String... fields)
+   {
+      for(String field : fields)
+      {
+         String value = "pii-sentinel-" + originals.size() + "-" + field;
+         originals.add(value);
+         record.withValue(field, value);
+      }
+      return (record);
+   }
+}

src/test/java/com/kingsrook/qbits/crm/CrmPresentationTest.java

@@ -0,0 +1,138 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.List;
+import com.kingsrook.qbits.crm.core.customizers.ContactLabelCustomizer;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.fields.DisplayFormat;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.Tier;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Presentation contracts remain stable across all discovered CRM metadata.
+ *******************************************************************************/
+class CrmPresentationTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Every table has an explicit human label and user identifiers read naturally.
+    *******************************************************************************/
+   @Test
+   void labelsAndMoney()
+   {
+      var instance = QContext.getQInstance();
+      for(var table : instance.getTables().values())
+      {
+         assertThat(table.getLabel()).isNotBlank().doesNotContain("_").isNotEqualToIgnoringCase(table.getName());
+         table.getFields().values().stream().filter(field -> field.getName().endsWith("UserId"))
+            .forEach(field -> assertThat(field.getLabel()).doesNotContain("User Id"));
+      }
+      assertThat(instance.getTable("crm_contact").getLabel()).isEqualTo("Contacts");
+      assertThat(instance.getTable("crm_deal").getField("amount").getDisplayFormat()).isEqualTo(DisplayFormat.CURRENCY);
+      assertThat(instance.getTable("crm_deal_product").getField("totalAmount").getDisplayFormat()).isEqualTo(DisplayFormat.CURRENCY);
+      assertThat(instance.getTable("crm_product").getField("unitPrice").getDisplayFormat()).isEqualTo(DisplayFormat.CURRENCY);
+      assertThat(instance.getTable("crm_sales_goal").getField("targetAmount").getDisplayFormat()).isEqualTo(DisplayFormat.CURRENCY);
+      for(String table : List.of("crm_contact", "crm_deal"))
+      {
+         assertThat(instance.getTable(table).getField("ownerUserId").getIsRequired()).isFalse();
+         assertThat(instance.getTable(table).getField("ownerUserId").getLabel()).isEqualTo("Owner");
+      }
+   }
+
+
+   /*******************************************************************************
+    ** All record-screen child lists have at most four valid, deliberate columns.
+    *******************************************************************************/
+   @Test
+   void sectionsAndChildLists()
+   {
+      var instance = QContext.getQInstance();
+      var contact = instance.getTable("crm_contact");
+      assertThat(contact.getSections()).extracting(section -> section.getName())
+         .contains("details", "contactInformation", "attribution", "system").doesNotContain("online", "address", "communication", "data", "dates");
+      assertThat(contact.getSections().stream().filter(section -> section.getName().equals("system")).findFirst().orElseThrow().getTier()).isEqualTo(Tier.T3);
+      for(String parent : List.of("crm_contact", "crm_company", "crm_deal"))
+      {
+         instance.getTable(parent).getSections().stream().filter(section -> section.getWidgetName() != null).forEach(section ->
+         {
+            var widget = instance.getWidget(section.getWidgetName());
+            if(widget.getDefaultValues() != null && widget.getDefaultValues().get("joinName") instanceof String joinName)
+            {
+               var child = instance.getTable(instance.getJoin(joinName).getRightTable());
+               List<?> fields = (List<?>) widget.getDefaultValues().get("onlyIncludeFieldNames");
+               assertThat(fields).isNotEmpty().hasSizeLessThanOrEqualTo(4);
+               fields.forEach(field -> assertThat(child.getFields()).containsKey(field.toString()));
+            }
+         });
+      }
+   }
+
+
+   /*******************************************************************************
+    ** A computed label must not re-expose fields omitted by the record view.
+    *******************************************************************************/
+   @Test
+   void hiddenNamesStayOutOfLabels() throws Exception
+   {
+      QRecord inserted = new InsertAction().execute(new InsertInput("crm_contact").withRecord(new QRecord()
+         .withValue("firstName", "Private").withValue("lastName", "Name").withValue("email", "visible@example.test"))).getRecords().getFirst();
+      var table = QContext.getQInstance().getTable("crm_contact");
+      table.getField("firstName").setIsHidden(true);
+      table.getField("lastName").setIsHidden(true);
+      var input = new com.kingsrook.qqq.backend.core.model.actions.tables.get.GetInput("crm_contact").withPrimaryKey(inserted.getValue("id"));
+      input.setShouldOmitHiddenFields(true);
+      QRecord visible = new GetAction().execute(input).getRecord();
+      assertThat(visible.getRecordLabel()).isEqualTo("visible@example.test");
+      assertThat(visible.getValue("firstName")).isNull();
+   }
+
+
+   /*******************************************************************************
+    ** Missing names remain null while get and query return useful record labels.
+    *******************************************************************************/
+   @Test
+   void contactNameFallbacks() throws Exception
+   {
+      for(String[] values : new String[][] {{"Ada", "Lovelace", "Ada Lovelace"}, {"Ada", null, "Ada"}, {null, null, "ada@example.test"}})
+      {
+         QRecord inserted = new InsertAction().execute(new InsertInput("crm_contact").withRecord(new QRecord()
+            .withValue("firstName", values[0]).withValue("lastName", values[1]).withValue("email", "ada@example.test"))).getRecords().getFirst();
+         assertThat(inserted.getErrors()).isNullOrEmpty();
+         QRecord record = GetAction.execute("crm_contact", inserted.getValue("id"));
+         assertThat(record.getRecordLabel()).isEqualTo(values[2]);
+         assertThat(record.getValue("lastName")).isEqualTo(values[1]);
+      }
+      assertThat(new QueryAction().execute(new QueryInput("crm_contact")).getRecords()).extracting(QRecord::getRecordLabel)
+         .containsExactly("Ada Lovelace", "Ada", "ada@example.test");
+      assertThat(ContactLabelCustomizer.label(new QRecord().withValue("firstName", "  ").withValue("lastName", " ").withValue("email", "mail@example.test")))
+         .isEqualTo("mail@example.test");
+   }
+}

src/test/java/com/kingsrook/qbits/crm/CrmPublicationHelpTest.java

@@ -0,0 +1,128 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.ArrayList;
+import java.util.List;
+import com.kingsrook.qqq.api.actions.GetTableApiFieldsAction;
+import com.kingsrook.qqq.api.model.APIVersion;
+import com.kingsrook.qqq.api.model.actions.GetTableApiFieldsInput;
+import com.kingsrook.qqq.api.model.metadata.ApiInstanceMetaData;
+import com.kingsrook.qqq.api.model.metadata.ApiInstanceMetaDataContainer;
+import com.kingsrook.qqq.api.model.metadata.tables.ApiTableMetaDataContainer;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.instances.QInstanceValidator;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
+import com.kingsrook.qqq.backend.core.testing.HelpBundleAssertions;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** Published fields, search declaration and shipped help coverage.
+ *******************************************************************************/
+class CrmPublicationHelpTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Api matches every published table.
+    *******************************************************************************/
+   @Test
+   void apiMatchesEveryPublishedTable() throws Exception
+   {
+      QInstance instance = P4TestSupport.host();
+      instance.withSupplementalMetaData(new ApiInstanceMetaDataContainer().withApiInstanceMetaData(new ApiInstanceMetaData()
+         .withName("host").withPath("/api/").withLabel("Host API").withDescription("CRM test API").withContactEmail("test@example.invalid").withCurrentVersion(new APIVersion("v1")).withSupportedVersions(List.of(new APIVersion("v1")))));
+      new CrmQBitProducer().withQBitConfig(new CrmQBitConfig().withDefaultBackendNameForTables(BACKEND_NAME)
+         .withApiName("host").withApiVersion("v1")).produce(instance).addSelfToInstance(instance);
+      new QInstanceValidator().validate(instance);
+      QContext.setQInstance(instance);
+      GetTableApiFieldsAction.clearCaches();
+      List<String> published = new ArrayList<>(CrmAppMetaData.MAIN_TABLES);
+      published.addAll(CrmAppMetaData.SETTINGS_TABLES);
+      for(String name : published)
+      {
+         var table = instance.getTable(name);
+         assertThat(ApiTableMetaDataContainer.of(table).getApiTableMetaData("host")).isNotNull();
+         var fields = GetTableApiFieldsAction.getTableApiFieldMap(new GetTableApiFieldsInput().withApiName("host").withVersion("v1").withTableName(name));
+         assertThat(fields.keySet()).as(name).containsExactlyInAnyOrderElementsOf(table.getFields().keySet());
+      }
+      assertThat(ApiTableMetaDataContainer.of(instance.getTable("crm_deal_product"))).isNull();
+      GetTableApiFieldsAction.clearCaches();
+   }
+
+
+   /*******************************************************************************
+    ** Esb fails closed until core excludes classified values.
+    *******************************************************************************/
+   @Test
+   void esbFailsClosedUntilCoreExcludesClassifiedValues()
+   {
+      assertThatThrownBy(() -> new CrmQBitProducer().withQBitConfig(new CrmQBitConfig()
+         .withDefaultBackendNameForTables(BACKEND_NAME).withEsbDestinationName("crmEvents")).produce(P4TestSupport.host()))
+         .hasMessageContaining("classified-value exclusion");
+   }
+
+
+   /*******************************************************************************
+    ** Main tables declare search fields.
+    *******************************************************************************/
+   @Test
+   void mainTablesDeclareSearchFields()
+   {
+      for(String table : CrmAppMetaData.MAIN_TABLES)
+      {
+         assertThat(QContext.getQInstance().getTable(table).getSearchFields()).isNotEmpty();
+      }
+      assertThat(QContext.getQInstance().getTable("crm_contact").getSearchFields()).containsExactly("firstName", "lastName", "email");
+      assertThat(QContext.getQInstance().getTable("crm_company").getSearchFields()).containsExactly("name", "domain");
+   }
+
+
+   /*******************************************************************************
+    ** Native registration is safe without help tables and covers all CRM metadata.
+    *******************************************************************************/
+   @Test
+   void helpCoversOwnedMetadataWithoutHelpTable()
+   {
+      var instance = QContext.getQInstance();
+      assertThat(instance.getTable("helpContent")).isNull();
+      assertThat(HelpBundles.of(instance).getBundles()).singleElement().satisfies(bundle ->
+      {
+         assertThat(bundle.getId()).isEqualTo("qbit-crm");
+         assertThat(bundle.getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CrmQBitProducer.VERSION);
+         assertThat(bundle.getLayer().name()).isEqualTo("QBIT");
+      });
+      HelpBundles.syncOnStartup(instance);
+      HelpBundleAssertions.forInstance(instance)
+         .bundles("help/qbit-crm.yaml")
+         .owning(target -> target.name().equals("crm") || target.name().startsWith("crm_") || target.name().startsWith("Crm"))
+         .assertComplete();
+      // Core's gate validates these entries but does not require widget or possible-value coverage.
+      var entries = HelpBundles.of(instance).resolveWinningEntries();
+      instance.getWidgets().keySet().stream().filter(name -> name.startsWith("crm_")).forEach(name ->
+         assertThat(entries).containsKey(new HelpBundles.EntryKey("widget:" + name + ";slot:label", "ALL_SCREENS")));
+      instance.getPossibleValueSources().keySet().stream().filter(name -> name.startsWith("crm_") || name.startsWith("Crm")).forEach(name ->
+         assertThat(entries).containsKey(new HelpBundles.EntryKey("possibleValueSource:" + name + ";slot:help", "ALL_SCREENS")));
+   }
+}

src/test/java/com/kingsrook/qbits/crm/CrmQBitConfigTest.java

@@ -29,10 +29,7 @@ package com.kingsrook.qbits.crm;
 import java.util.ArrayList;
 import java.util.List;
 import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
-import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldMetaData;
-import com.kingsrook.qqq.backend.core.model.metadata.fields.QFieldType;
 import com.kingsrook.qqq.backend.core.model.metadata.producers.MetaDataCustomizerInterface;
-import com.kingsrook.qqq.backend.core.model.metadata.security.RecordSecurityLock;
 import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
 import org.junit.jupiter.api.Test;
 import static org.assertj.core.api.Assertions.assertThat;
@@ -50,26 +47,20 @@ class CrmQBitConfigTest
    @Test
    void testFluentSettersAndGetters()
    {
-      List<QFieldMetaData> securityFields = List.of(
-         new QFieldMetaData("tenantId", QFieldType.INTEGER));
-
-      List<RecordSecurityLock> locks = List.of(
-         new RecordSecurityLock().withFieldName("tenantId"));
-
       MetaDataCustomizerInterface<QTableMetaData> customizer = (qInstance, table) -> table;
 
       CrmQBitConfig config = new CrmQBitConfig()
          .withDefaultBackendNameForTables("myBackend")
          .withInferBackendNames(false)
          .withTableMetaDataCustomizer(customizer)
-         .withSecurityFields(securityFields)
-         .withRecordSecurityLocks(locks);
+         .withTenantSecurityKeyType("tenant")
+         .withTenantAllAccessKeyName("allTenants");
 
       assertThat(config.getDefaultBackendNameForTables()).isEqualTo("myBackend");
       assertThat(config.getInferBackendNames()).isFalse();
       assertThat(config.getTableMetaDataCustomizer()).isSameAs(customizer);
-      assertThat(config.getSecurityFields()).isSameAs(securityFields);
-      assertThat(config.getRecordSecurityLocks()).isSameAs(locks);
+      assertThat(config.getTenantSecurityKeyType()).isEqualTo("tenant");
+      assertThat(config.getTenantAllAccessKeyName()).isEqualTo("allTenants");
    }
 
 

src/test/java/com/kingsrook/qbits/crm/CrmQBitProducerTest.java

@@ -62,7 +62,7 @@ class CrmQBitProducerTest extends BaseTest
       assertThat(metaData).isNotNull();
       assertThat(metaData.getGroupId()).isEqualTo(CrmQBitProducer.GROUP_ID);
       assertThat(metaData.getArtifactId()).isEqualTo(CrmQBitProducer.ARTIFACT_ID);
-      assertThat(metaData.getVersion()).isEqualTo(CrmQBitProducer.VERSION);
+      assertThat(metaData.getVersion()).isEqualTo(System.getProperty("qbit.artifactVersion")).isEqualTo(CrmQBitProducer.VERSION);
    }
 
 
@@ -114,7 +114,7 @@ class CrmQBitProducerTest extends BaseTest
    {
       assertThat(CrmQBitProducer.GROUP_ID).isEqualTo("com.kingsrook.qbits");
       assertThat(CrmQBitProducer.ARTIFACT_ID).isEqualTo("crm");
-      assertThat(CrmQBitProducer.VERSION).isEqualTo("0.2.0-SNAPSHOT");
+      assertThat(CrmQBitProducer.VERSION).isEqualTo(System.getProperty("qbit.artifactVersion"));
    }
 
    /*******************************************************************************
@@ -142,7 +142,7 @@ class CrmQBitProducerTest extends BaseTest
       {
          assertThat(QContext.getQInstance().getTable(tableName).getAuditRules().getAuditLevel()).isEqualTo(AuditLevel.FIELD);
       }
-      assertThat(QContext.getQInstance().getTables()).hasSize(33)
+      assertThat(QContext.getQInstance().getTables()).hasSize(34)
          .doesNotContainKeys("crm_tag", "crm_contact_tag", "crm_company_tag", "crm_deal_tag", "crm_attachment", "crm_audit_log");
       assertThat(QContext.getQInstance().getProcesses()).doesNotContainKeys("crm_bulk_add_tag", "crm_bulk_remove_tag");
    }

src/test/java/com/kingsrook/qbits/crm/CrmRdbmsTest.java

@@ -226,7 +226,7 @@ class CrmRdbmsTest
    @Test
    void testSchemaMatchesMetadata() throws Exception
    {
-      assertThat(qInstance.getTables()).hasSize(33);
+      assertThat(qInstance.getTables()).hasSize(34);
       for(QTableMetaData table : qInstance.getTables().values())
       {
          Set<String> columns = new HashSet<>();
@@ -270,20 +270,41 @@ class CrmRdbmsTest
 
 
    /*******************************************************************************
-    ** Both install paths contain identical SQL, with one Liquibase changeset per table.
+    ** Fresh DDL and the full upgrade changelog produce identical column definitions.
     *******************************************************************************/
    @Test
    void testLiquibaseMatchesReferenceDdl() throws Exception
    {
-      String ddl = Files.readString(Path.of("docs/ddl/postgres.sql"));
       String changelog = Files.readString(Path.of("src/main/resources/db/liquibase/qbit-crm/crm.changelog.sql"));
       assertThat(changelog).startsWith("--liquibase formatted sql");
-      assertThat(changelog.lines().filter(line -> line.startsWith("--changeset qbit-crm:")).count()).isEqualTo(33);
-      assertThat(stripComments(changelog)).isEqualTo(stripComments(ddl));
+      assertThat(changelog.lines().filter(line -> line.startsWith("--changeset qbit-crm:")).count()).isEqualTo(35);
+      var freshColumns = schemaColumns();
+      executeSql("DROP ALL OBJECTS;");
+      executeSql(changelog);
+      assertThat(schemaColumns()).isEqualTo(freshColumns);
+      insert("crm_contact", new QRecord().withValue("email", "email-only@example.test"));
    }
 
 
 
+   /*******************************************************************************
+    ** Capture persisted types and nullability for both installation paths.
+    *******************************************************************************/
+   private java.util.Map<String, String> schemaColumns() throws Exception
+   {
+      java.util.Map<String, String> columns = new java.util.TreeMap<>();
+      try(ResultSet rows = connection.getMetaData().getColumns(null, "public", "crm_%", null))
+      {
+         while(rows.next())
+         {
+            columns.put(rows.getString("TABLE_NAME") + "." + rows.getString("COLUMN_NAME"),
+               rows.getString("TYPE_NAME") + ":" + rows.getInt("COLUMN_SIZE") + ":" + rows.getInt("NULLABLE"));
+         }
+      }
+      return (columns);
+   }
+
+
    /*******************************************************************************
     ** Insert through QQQ and fail on record-level validation errors.
     *******************************************************************************/
@@ -359,7 +380,7 @@ class CrmRdbmsTest
       input.setWidgetMetaData(qInstance.getWidget("crm_pipeline_summary"));
       TableData pipeline = (TableData) renderer.execute(input).getWidgetData();
       assertThat(pipeline.getRows()).hasSize(2);
-      assertThat(pipeline.getRows().getFirst().get("first").toString()).endsWith(">Open (1 deals)</a>");
+      assertThat(pipeline.getRows().getFirst().get("first").toString()).endsWith(">Open</a>");
       input.setWidgetMetaData(qInstance.getWidget("crm_deal_forecast"));
       TableData forecast = (TableData) renderer.execute(input).getWidgetData();
       assertThat(forecast.getRows()).hasSize(6);
@@ -370,4 +391,31 @@ class CrmRdbmsTest
       assertThat(leaders.getRows().getFirst().get("first").toString()).endsWith(">Ada</a>");
    }
 
+
+   /*******************************************************************************
+    ** The base schema stays unchanged; only the explicit tenant migration adds keys.
+    *******************************************************************************/
+   @Test
+   void testOptionalTenantSchemaMatchesMetadata() throws Exception
+   {
+      try(var columns = connection.getMetaData().getColumns(null, null, "crm_contact", "tenant_key"))
+      {
+         assertThat(columns.next()).isFalse();
+      }
+      executeSql(Files.readString(Path.of("src/main/resources/db/liquibase/qbit-crm/crm-tenancy.changelog.sql")));
+      QInstance tenantInstance = new QInstance();
+      tenantInstance.addBackend(qInstance.getBackend("rdbms"));
+      tenantInstance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("anonymous").withType(QAuthenticationType.FULLY_ANONYMOUS));
+      new CrmQBitProducer().withQBitConfig(new CrmQBitConfig().withDefaultBackendNameForTables("rdbms")
+         .withTenantSecurityKeyType("tenant")).produce(tenantInstance).addSelfToInstance(tenantInstance);
+      new QInstanceValidator().validate(tenantInstance);
+      for(var table : tenantInstance.getTables().values())
+      {
+         try(var columns = connection.getMetaData().getColumns(null, null, table.getName(), "tenant_key"))
+         {
+            assertThat(columns.next()).as(table.getName()).isEqualTo(table.getFields().containsKey("tenantKey"));
+         }
+      }
+   }
+
 }

src/test/java/com/kingsrook/qbits/crm/CrmRelationshipValidationTest.java

@@ -0,0 +1,76 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.List;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Relationship validation must cover insert and either side of partial updates.
+ *******************************************************************************/
+class CrmRelationshipValidationTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Rejects wrong pipeline on insert and partial updates.
+    *******************************************************************************/
+   @Test
+   void rejectsWrongPipelineOnInsertAndPartialUpdates() throws Exception
+   {
+      P4TestSupport.seed("crm_pipeline_stage", new QRecord().withValue("id", 10).withValue("pipelineId", 1),
+         new QRecord().withValue("id", 20).withValue("pipelineId", 2));
+      var inserted = new InsertAction().execute(new InsertInput("crm_deal").withRecord(new QRecord().withValue("name", "Wrong stage")
+         .withValue("pipelineId", 1).withValue("pipelineStageId", 20)));
+      assertThat(inserted.getRecords().getFirst().getErrors()).isNotEmpty();
+      P4TestSupport.seed("crm_deal", new QRecord().withValue("id", 1).withValue("name", "Existing").withValue("pipelineId", 1).withValue("pipelineStageId", 10));
+      for(QRecord change : List.of(new QRecord().withValue("id", 1).withValue("pipelineId", 2),
+         new QRecord().withValue("id", 1).withValue("pipelineStageId", 20)))
+      {
+         assertThat(new UpdateAction().execute(new UpdateInput("crm_deal").withRecord(change)).getRecords().getFirst().getErrors()).isNotEmpty();
+      }
+   }
+
+
+   /*******************************************************************************
+    ** Validates activity outcome and allows null outcome.
+    *******************************************************************************/
+   @Test
+   void validatesActivityOutcomeAndAllowsNullOutcome() throws Exception
+   {
+      P4TestSupport.seed("crm_activity_outcome", new QRecord().withValue("id", 10).withValue("activityTypeId", 1));
+      var bad = new InsertAction().execute(new InsertInput("crm_activity").withRecord(new QRecord().withValue("subject", "Wrong outcome")
+         .withValue("activityTypeId", 2).withValue("outcomeId", 10)));
+      assertThat(bad.getRecords().getFirst().getErrors()).isNotEmpty();
+      var good = new InsertAction().execute(new InsertInput("crm_activity").withRecord(new QRecord().withValue("subject", "Call").withValue("ownerUserId", TEST_USER_ID)
+         .withValue("activityTypeId", 1).withValue("outcomeId", 10)));
+      assertThat(good.getRecords().getFirst().getErrors()).isNullOrEmpty();
+      var cleared = new UpdateAction().execute(new UpdateInput("crm_activity").withRecord(new QRecord()
+         .withValue("id", good.getRecords().getFirst().getValue("id")).withValue("outcomeId", null)));
+      assertThat(cleared.getRecords().getFirst().getErrors()).isNullOrEmpty();
+   }
+}

src/test/java/com/kingsrook/qbits/crm/CrmTablesGuardrailTest.java

@@ -0,0 +1,263 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import java.util.stream.Stream;
+import com.kingsrook.qqq.backend.core.model.metadata.help.bundles.HelpBundles;
+import com.kingsrook.qqq.backend.core.model.metadata.tables.QTableMetaData;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** Guardrail (owner requirement 2026-10-14: every table populated, used and
+ ** self-explaining). For every crm_* table:
+ ** - runtime code (not just its model, metadata or setup card) reads or writes
+ **   it, or the table is listed here as having no runtime code and why;
+ ** - it is either seeded by the shipped defaults changelog, or listed here
+ **   with why it starts empty;
+ ** - it has bundle help that says how its rows get created (shown on the table
+ **   screen and when it is empty).
+ ** A new table fails this test until it is wired, seeded or explained.
+ *******************************************************************************/
+class CrmTablesGuardrailTest extends BaseTest
+{
+   private static final Path MAIN = Path.of("src", "main", "java", "com", "kingsrook", "qbits", "crm");
+
+   /*******************************************************************************
+    ** Metadata and presentation files: naming a table here is not using it.
+    *******************************************************************************/
+   private static final Set<String> NOT_RUNTIME = Set.of("CrmAppMetaData.java", "CrmPresentation.java", "CrmPermissions.java",
+      "CrmDataPolicy.java", "CrmSetupStatus.java", "CrmIntegrations.java");
+
+   /*******************************************************************************
+    ** Tables that legitimately start empty, and where their rows come from.
+    *******************************************************************************/
+   static final Map<String, String> STARTS_EMPTY = Map.ofEntries(
+      Map.entry("crm_contact", "user content: people, imports, converted web leads"),
+      Map.entry("crm_company", "user content"),
+      Map.entry("crm_deal", "user content: New, or Create Deal on a contact"),
+      Map.entry("crm_deal_contact", "user content: Add Contact on a deal"),
+      Map.entry("crm_deal_product", "user content: product lines on a deal"),
+      Map.entry("crm_deal_stage_history", "runtime: a deal is created or changes stage"),
+      Map.entry("crm_activity", "user content: Log Activity"),
+      Map.entry("crm_activity_participant", "user content: people added to an activity"),
+      Map.entry("crm_form_submission", "runtime: the host's public intake call"),
+      Map.entry("crm_consent_record", "runtime: evidence written when a consent decision is made"),
+      Map.entry("crm_email_list", "user content: lists are the business's own"),
+      Map.entry("crm_email_list_member", "runtime: subscribing a contact or address"),
+      Map.entry("crm_email_message", "runtime: every email sent or received"),
+      Map.entry("crm_email_template", "user content: the wording is the business's own"),
+      Map.entry("crm_email_sequence", "user content: the outreach is the business's own"),
+      Map.entry("crm_sequence_step", "user content: steps of a sequence"),
+      Map.entry("crm_sequence_enrollment", "runtime: Enroll in Sequence"),
+      Map.entry("crm_product", "user content: the catalogue is the business's own"),
+      Map.entry("crm_sales_goal", "user content: targets per user and period"),
+      Map.entry("crm_lead_score_rule", "business-specific: good scoring depends on the business"),
+      Map.entry("crm_assignment_rule", "host-specific: rules name the host's users"),
+      Map.entry("crm_assignment_rule_member", "host-specific: the host's users"),
+      Map.entry("crm_job_state", "runtime: a scheduled maintenance run saves its checkpoint"),
+      Map.entry("crm_external_mapping", "not wired: nothing in the CRM writes it (reserved for a host integration)"));
+
+   /*******************************************************************************
+    ** Tables no CRM code reads or writes: their rows are the user's own, added
+    ** and edited through the standard table screens and the published API.
+    *******************************************************************************/
+   static final Map<String, String> USER_OWNED_NO_CODE = Map.of(
+      "crm_activity_participant", "user-owned child rows added on an activity's record",
+      "crm_product", "user-owned catalogue; deal product lines pick from it (possible values, line item screens)",
+      "crm_industry", "reference list consumed only through the Industry picker on a company (possible values)");
+
+
+
+   /*******************************************************************************
+    ** Tables with no writer in the CRM; their help must say so.
+    *******************************************************************************/
+   static final Set<String> NOT_WRITTEN_YET = Set.of("crm_external_mapping");
+
+
+
+   /*******************************************************************************
+    ** Every table is used by runtime code.
+    *******************************************************************************/
+   @Test
+   void everyTableIsUsedAtRuntime() throws Exception
+   {
+      Map<String, String> entityByTable = entityByTable();
+      List<String>        runtimeSource;
+      try(Stream<Path> files = Files.walk(MAIN))
+      {
+         runtimeSource = files.filter(p -> p.toString().endsWith(".java")).filter(p -> !p.toString().replace('\\', '/').contains("/model/"))
+            .filter(p -> !NOT_RUNTIME.contains(p.getFileName().toString())).map(CrmTablesGuardrailTest::read).toList();
+      }
+      for(String table : crmTables())
+      {
+         if(USER_OWNED_NO_CODE.containsKey(table))
+         {
+            continue;
+         }
+         String  entity    = entityByTable.get(table);
+         Pattern entityUse = Pattern.compile("\\b" + entity + "(\\.TABLE_NAME|\\.class|\\(|::)");
+         assertThat(entity).as("entity class for " + table).isNotNull();
+         assertThat(runtimeSource.stream().anyMatch(source -> source.contains("\"" + table + "\"") || entityUse.matcher(source).find()))
+            .as(table + " (" + entity + ") must be read or written by runtime code, not only declared").isTrue();
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Every table is seeded or explained.
+    *******************************************************************************/
+   @Test
+   void everyTableIsSeededOrExplained() throws Exception
+   {
+      String changelog = CrmDefaultsChangelogTest.resource(CrmDefaultsChangelogTest.CHANGELOG);
+      for(String table : crmTables())
+      {
+         boolean seeded = CrmDefaultsChangelogTest.SEEDED_TABLES.contains(table);
+         assertThat(seeded || STARTS_EMPTY.containsKey(table)).as(table + " must be seeded by the defaults changelog or listed in STARTS_EMPTY").isTrue();
+         assertThat(seeded && STARTS_EMPTY.containsKey(table)).as(table + " cannot be both seeded and listed as starting empty").isFalse();
+         assertThat(changelog.contains("INSERT INTO " + table + " ")).as(table + " seeded iff the changelog inserts it").isEqualTo(seeded);
+      }
+      assertThat(STARTS_EMPTY.keySet()).allMatch(table -> qInstance().getTable(table) != null, "STARTS_EMPTY names only real tables");
+   }
+
+
+
+   /*******************************************************************************
+    ** Every table and the app have bundle help that says how rows get created.
+    *******************************************************************************/
+   @Test
+   void everyTableHasEmptyStateHelp() throws Exception
+   {
+      HelpBundles.of(qInstance()).getBundles().getFirst().getEntries()
+         .forEach(entry -> assertThat(entry.getSummary()).as(entry.getKey()).hasSizeLessThanOrEqualTo(120));
+      for(String table : crmTables())
+      {
+         assertThat(tableHelp(table)).as(table + " help says how rows get created").contains("**How rows get created:**");
+      }
+      for(String table : NOT_WRITTEN_YET)
+      {
+         assertThat(tableHelp(table)).as(table + " says it is not used yet").contains("not used yet");
+      }
+      assertThat(HelpBundles.of(qInstance()).resolveWinningEntries()).containsKey(new HelpBundles.EntryKey("app:crm;slot:help", "ALL_SCREENS"));
+   }
+
+
+
+   /*******************************************************************************
+    ** The tables seeded by the changelog are the ones the help says are seeded.
+    *******************************************************************************/
+   @Test
+   void helpOfSeededTablesSaysSo() throws Exception
+   {
+      for(String table : CrmDefaultsChangelogTest.SEEDED_TABLES)
+      {
+         assertThat(tableHelp(table)).as(table).contains("seeds");
+      }
+   }
+
+
+
+   /*******************************************************************************
+    ** Read the winning table entry from the registered native bundle.
+    *******************************************************************************/
+   private String tableHelp(String table)
+   {
+      var entry = HelpBundles.of(qInstance()).resolveWinningEntries().get(new HelpBundles.EntryKey("table:" + table + ";slot:help", "ALL_SCREENS"));
+      assertThat(entry).as(table + " table help").isNotNull();
+      return (entry.entry().getContent());
+   }
+
+
+
+   /*******************************************************************************
+    ** Test instance after CRM production.
+    *******************************************************************************/
+   private com.kingsrook.qqq.backend.core.model.metadata.QInstance qInstance()
+   {
+      return (com.kingsrook.qqq.backend.core.context.QContext.getQInstance());
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private List<String> crmTables()
+   {
+      List<String> tables = qInstance().getTables().values().stream().map(QTableMetaData::getName).filter(n -> n.startsWith("crm_")).sorted().toList();
+      assertThat(tables).hasSize(34);
+      return (tables);
+   }
+
+
+
+   /*******************************************************************************
+    ** model/X.java declares TABLE_NAME = "x".
+    *******************************************************************************/
+   private static Map<String, String> entityByTable() throws Exception
+   {
+      Map<String, String> rs = new HashMap<>();
+      Pattern             p  = Pattern.compile("TABLE_NAME\\s*=\\s*\"([a-z_]+)\"");
+      try(Stream<Path> files = Files.walk(MAIN))
+      {
+         for(Path file : files.filter(f -> f.toString().endsWith(".java")).toList())
+         {
+            Matcher m = p.matcher(read(file));
+            if(m.find())
+            {
+               rs.put(m.group(1), file.getFileName().toString().replace(".java", ""));
+            }
+         }
+      }
+      return (rs);
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String read(Path path)
+   {
+      try
+      {
+         return (Files.readString(path, StandardCharsets.UTF_8));
+      }
+      catch(Exception e)
+      {
+         throw (new IllegalStateException(e));
+      }
+   }
+
+}

src/test/java/com/kingsrook/qbits/crm/P4TestSupport.java

@@ -0,0 +1,67 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.QAuthenticationType;
+import com.kingsrook.qqq.backend.core.model.metadata.QBackendMetaData;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.metadata.authentication.QAuthenticationMetaData;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryBackendModule;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
+
+
+/*******************************************************************************
+ ** Isolated host instances and fixture inserts, without bypassing actions under test.
+ *******************************************************************************/
+final class P4TestSupport
+{
+   /*******************************************************************************
+    ** Utility class.
+    *******************************************************************************/
+   private P4TestSupport()
+   {
+   }
+
+
+   /*******************************************************************************
+    ** Build a host without CRM, ready for configuration-specific production.
+    *******************************************************************************/
+   static QInstance host()
+   {
+      QInstance instance = new QInstance();
+      instance.withInstanceDefaultAuthentication(new QAuthenticationMetaData().withName("anonymous").withType(QAuthenticationType.FULLY_ANONYMOUS));
+      instance.addBackend(new QBackendMetaData().withName("memory").withBackendType(MemoryBackendModule.class));
+      return (instance);
+   }
+
+
+   /*******************************************************************************
+    ** Fixture storage intentionally avoids business side effects.
+    *******************************************************************************/
+   static void seed(String table, QRecord... rows) throws QException
+   {
+      MemoryRecordStore.getInstance().insert(new InsertInput(table).withRecords(java.util.List.of(rows)), false);
+   }
+}

src/test/java/com/kingsrook/qbits/crm/PlatformReuseTest.java

@@ -0,0 +1,790 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.temporal.ChronoUnit;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+import com.kingsrook.qbits.crm.actions.CrmAction;
+import com.kingsrook.qbits.crm.actions.CrmActions;
+import com.kingsrook.qbits.crm.api.CrmApi;
+import com.kingsrook.qbits.crm.api.CrmReadiness;
+import com.kingsrook.qbits.crm.core.CrmRecords;
+import com.kingsrook.qbits.crm.core.model.enums.CrmAssignStrategy;
+import com.kingsrook.qbits.crm.core.model.enums.CrmAssignableEntity;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmConsentType;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEmailStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmEnrollmentStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmListMemberStatus;
+import com.kingsrook.qbits.crm.core.model.enums.CrmScoreOperator;
+import com.kingsrook.qbits.crm.core.model.enums.CrmSequenceStepType;
+import com.kingsrook.qbits.crm.deals.CrmDealNotifications;
+import com.kingsrook.qbits.crm.email.CrmEmailProcessIdentity;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.email.CrmEmails;
+import com.kingsrook.qbits.crm.email.processes.ExpireConsentsProcess;
+import com.kingsrook.qbits.crm.email.processes.ProcessSequenceStepsProcess;
+import com.kingsrook.qbits.crm.email.processes.SyncEmailDeliveryProcess;
+import com.kingsrook.qbits.crm.scoring.processes.CalculateLeadScoresProcess;
+import com.kingsrook.qqq.backend.core.actions.processes.RunProcessAction;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.QueryAction;
+import com.kingsrook.qqq.backend.core.alerts.AlertResolution;
+import com.kingsrook.qqq.backend.core.alerts.AlertSignal;
+import com.kingsrook.qqq.backend.core.alerts.AlertsInstanceMetaData;
+import com.kingsrook.qqq.backend.core.alerts.LoggingAlertSink;
+import com.kingsrook.qqq.backend.core.alerts.NotificationAudience;
+import com.kingsrook.qqq.backend.core.alerts.NotificationSignal;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QException;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunProcessInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.query.QueryInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import com.kingsrook.qqq.backend.core.model.metadata.code.QCodeReference;
+import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeature;
+import com.kingsrook.qqq.backend.core.model.metadata.collaboration.RecordFeaturesMetaData;
+import com.kingsrook.qqq.backend.core.modules.backend.implementations.memory.MemoryRecordStore;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+
+/*******************************************************************************
+ ** P4 contracts exercised through memory DML, fake transport and real QAlerts dispatch.
+ *******************************************************************************/
+class PlatformReuseTest extends BaseTest
+{
+   private FakeTransport transport;
+
+   /*******************************************************************************
+    ** Keep effects local to this test.
+    *******************************************************************************/
+   @BeforeEach
+   void configure() throws Exception
+   {
+      transport = new FakeTransport();
+      CrmApi.config().withPublicBaseUrl("https://crm.example.test").withTokenSecret("test-only-signing-key");
+      Sink.notifications.clear();
+      Sink.alerts.clear();
+      Sink.resolutions.clear();
+      AlertsInstanceMetaData.ofOrWithNew(QContext.getQInstance()).withSink(new QCodeReference(Sink.class));
+   }
+
+   /*******************************************************************************
+    ** Send action renders and records transactional delivery.
+    *******************************************************************************/
+   @Test
+   void sendActionRendersAndRecordsTransactionalDelivery() throws Exception
+   {
+      QRecord contact = contact(1).withValue("companyId", 1);
+      put("crm_company", new QRecord().withValue("id", 1).withValue("name", "Example"));
+      put("crm_contact", contact);
+      put("crm_email_template", new QRecord().withValue("id", 1).withValue("subject", "Hello {{contact.firstName}}")
+         .withValue("bodyText", "{{contact.lastName}} at {{company.name}} / {{owner.name}} / {{unsubscribeUrl}}"));
+      CrmAction.Load load = load();
+      RunBackendStepInput input = new RunBackendStepInput().withProcessName("crm_send_email").withRecords(List.of(contact))
+         .addValue("emailTemplateId", 1).addValue("crmEmailProcessUUID", "run-123");
+      load.runOnePage(input, new RunBackendStepOutput());
+      assertThat(transport.key).isEqualTo("crm:email:1:run-123");
+      assertThat(transport.marketing).isFalse();
+      assertThat(transport.subject).isEqualTo("Hello Alice");
+      assertThat(transport.body).startsWith("Smith at Example / owner / https://crm.example.test/qqq/hooks/crm/unsubscribe/");
+      assertThat(rows("crm_email_message")).singleElement().satisfies(row ->
+      {
+         assertThat(row.getValueInteger("status")).isEqualTo(CrmEmailStatus.QUEUED.getId());
+         assertThat(row.getValueString("emailMessageId")).isEqualTo("provider-1");
+         assertThat(row.getValueString("idempotencyKey")).isEqualTo(transport.key);
+      });
+      assertActivity("EMAIL");
+      load.runOnePage(input, new RunBackendStepOutput());
+      assertThat(transport.sends).isEqualTo(1);
+      assertThat(rows("crm_activity")).hasSize(1);
+   }
+
+   /*******************************************************************************
+    ** Overrides and missing templates and literal merge values.
+    *******************************************************************************/
+   @Test
+   void overridesAndMissingTemplatesAndLiteralMergeValues() throws Exception
+   {
+      QRecord contact = contact(1).withValue("firstName", "{{owner.name}}");
+      assertThat(CrmEmails.render("{{contact.firstName}} {{contact.lastName}}", contact)).isEqualTo("{{owner.name}} Smith");
+      assertThrows(QException.class, () -> CrmEmails.send(transport, contact, 999, null, null, "email", "missing", null));
+      assertThrows(QException.class, () -> CrmEmails.send(transport, contact, null, "subject", "", "email", "missing", null));
+      put("crm_email_template", new QRecord().withValue("id", 1).withValue("subject", "template").withValue("bodyText", "template"));
+      CrmEmails.send(transport, contact, 1, "override", "body", "email", "1:run", null);
+      assertThat(transport.subject).isEqualTo("override");
+      assertThat(transport.body).isEqualTo("body");
+   }
+
+   /*******************************************************************************
+    ** Skips opt out missing address and unavailable transport.
+    *******************************************************************************/
+   @Test
+   void skipsOptOutMissingAddressAndUnavailableTransport() throws Exception
+   {
+      List<QRecord> contacts = List.of(contact(1).withValue("doNotEmail", true), contact(2).withValue("email", null), contact(3));
+      for(QRecord contact : contacts)
+      {
+         put("crm_contact", contact);
+      }
+      transport.ready = false;
+      CrmAction.Load load = load();
+      RunBackendStepOutput output = new RunBackendStepOutput();
+      load.runOnePage(new RunBackendStepInput().withProcessName("crm_send_email").withRecords(contacts), output);
+      assertThat(load.getProcessSummary(output, true)).hasSize(3);
+      assertThat(transport.sends).isZero();
+      assertThat(rows("crm_email_message")).isEmpty();
+      assertThat(rows("crm_activity")).isEmpty();
+   }
+
+   /*******************************************************************************
+    ** Process identity uses core uuid.
+    *******************************************************************************/
+   @Test
+   void processIdentityUsesCoreUuid() throws Exception
+   {
+      var output = new RunProcessAction().execute(new RunProcessInput().withProcessName("crm_send_email"));
+      assertThat(output.getException()).isEmpty();
+      assertThat(output.getValues().get("crmEmailProcessUUID")).isEqualTo(output.getProcessUUID());
+      var listener = new CrmEmailProcessIdentity();
+      assertThat(listener.appliesTo("crm_send_email")).isTrue();
+      assertThat(listener.appliesTo("crm_other")).isFalse();
+      listener.onProcessCompleted(new RunProcessInput(), output);
+      listener.onProcessFailed(new RunProcessInput(), new Exception("test"));
+      assertThat(CrmActions.inputFields(CrmActions.action("crm_send_email"))).extracting(field -> field.getName())
+         .containsExactly("emailTemplateId", "subject", "body");
+   }
+
+   /*******************************************************************************
+    ** Active sequence sends marketing and advances once.
+    *******************************************************************************/
+   @Test
+   void activeSequenceSendsMarketingAndAdvancesOnce() throws Exception
+   {
+      seedSequence(true, true);
+      sequence();
+      assertThat(transport.key).isEqualTo("crm:seq:1:1");
+      assertThat(transport.marketing).isTrue();
+      assertThat(rows("crm_email_message")).hasSize(1);
+      assertActivity("SEQUENCE_STEP");
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("status")).isEqualTo(CrmEnrollmentStatus.COMPLETED.getId());
+      sequence();
+      assertThat(transport.sends).isEqualTo(1);
+   }
+
+   /*******************************************************************************
+    ** Paused sequence does not advance or send.
+    *******************************************************************************/
+   @Test
+   void pausedSequenceDoesNotAdvanceOrSend() throws Exception
+   {
+      seedSequence(false, true);
+      sequence();
+      assertThat(transport.sends).isZero();
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("currentStepNumber")).isZero();
+      assertThat(Sink.alerts).isEmpty();
+   }
+
+   /*******************************************************************************
+    ** Missing consent pauses enrollment with reason.
+    *******************************************************************************/
+   @Test
+   void missingConsentPausesEnrollmentWithReason() throws Exception
+   {
+      seedSequence(true, false);
+      sequence();
+      QRecord enrollment = GetAction.execute("crm_sequence_enrollment", 1);
+      assertThat(enrollment.getValueInteger("status")).isEqualTo(CrmEnrollmentStatus.PAUSED.getId());
+      assertThat(enrollment.getValueString("lastFailureMessage")).isEqualTo("no_email_consent");
+      assertThat(enrollment.getValueInteger("failureCount")).isZero();
+      assertThat(transport.sends).isZero();
+   }
+
+   /*******************************************************************************
+    ** Transport failures raise on third attempt.
+    *******************************************************************************/
+   @Test
+   void transportFailuresRaiseOnThirdAttempt() throws Exception
+   {
+      seedSequence(true, true);
+      transport.fail = true;
+      sequence();
+      sequence();
+      sequence();
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("failureCount")).isEqualTo(3);
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("status")).isEqualTo(CrmEnrollmentStatus.FAILED.getId());
+      assertThat(Sink.alerts).singleElement().satisfies(signal ->
+      {
+         assertThat(signal.getAlertTypeName()).isEqualTo("crm.sequence.failing");
+         assertThat(signal.getDedupKey()).isEqualTo("enrollment:1");
+      });
+      assertThat(rows("crm_email_message")).isEmpty();
+   }
+
+   /*******************************************************************************
+    ** Unavailable transport raises then resolves without failing enrollment.
+    *******************************************************************************/
+   @Test
+   void unavailableTransportRaisesThenResolvesWithoutFailingEnrollment() throws Exception
+   {
+      seedSequence(true, true);
+      transport.ready = false;
+      sequence();
+      assertThat(Sink.alerts).singleElement().satisfies(signal ->
+      {
+         assertThat(signal.getAlertTypeName()).isEqualTo("crm.email.unavailable");
+         assertThat(signal.getDedupKey()).isEqualTo("transport");
+      });
+      assertThat(GetAction.execute("crm_sequence_enrollment", 1).getValueInteger("failureCount")).isZero();
+      transport.ready = true;
+      sequence();
+      assertThat(Sink.resolutions).hasSize(1);
+      assertThat(transport.sends).isEqualTo(1);
+   }
+
+   /*******************************************************************************
+    ** Delivery sync uses recent nonfinal messages and preserves dates.
+    *******************************************************************************/
+   @Test
+   void deliverySyncUsesRecentNonfinalMessagesAndPreservesDates() throws Exception
+   {
+      contact(1);
+      message(1, CrmEmailStatus.SENT, Instant.now());
+      message(2, CrmEmailStatus.SENT, Instant.now().minus(31, ChronoUnit.DAYS));
+      message(3, CrmEmailStatus.FAILED, Instant.now());
+      Instant now = Instant.now();
+      transport.deliveries.put("key:1", new CrmEmailTransport.Delivery("provider", CrmEmailStatus.CLICKED, now, now, now, now, null));
+      sync();
+      assertThat(transport.lookups).containsExactly("key:1");
+      QRecord message = GetAction.execute("crm_email_message", 1);
+      assertThat(message.getValueInstant("deliveredDate")).isEqualTo(now);
+      assertThat(message.getValueInstant("firstOpenedDate")).isEqualTo(now);
+      assertThat(message.getValueInstant("firstClickedDate")).isEqualTo(now);
+      transport.deliveries.put("key:1", new CrmEmailTransport.Delivery("provider", CrmEmailStatus.CLICKED, null, null, null, null, null));
+      sync();
+      assertThat(GetAction.execute("crm_email_message", 1).getValueInstant("firstOpenedDate")).isEqualTo(now);
+   }
+
+   /*******************************************************************************
+    ** Bounce and complaint withdraw once and suppress contact.
+    *******************************************************************************/
+   @Test
+   void bounceAndComplaintWithdrawOnceAndSuppressContact() throws Exception
+   {
+      for(int id = 1; id <= 2; id++)
+      {
+         contact(id);
+         message(id, CrmEmailStatus.DELIVERED, Instant.now());
+         CrmEmailStatus status = id == 1 ? CrmEmailStatus.BOUNCED : CrmEmailStatus.COMPLAINED;
+         transport.deliveries.put("key:" + id, new CrmEmailTransport.Delivery("provider", status, null, null, null, null, Instant.now()));
+      }
+      sync();
+      sync();
+      assertThat(rows("crm_contact")).allSatisfy(row -> assertThat(row.getValueBoolean("doNotEmail")).isTrue());
+      assertThat(rows("crm_consent_record")).hasSize(2).allSatisfy(row ->
+      {
+         assertThat(row.getValueInteger("consentType")).isEqualTo(CrmConsentType.EMAIL.getId());
+         assertThat(row.getValueInteger("status")).isEqualTo(CrmConsentStatus.WITHDRAWN.getId());
+      });
+      assertThat(rows("crm_consent_record")).extracting(row -> row.getValueString("source")).containsExactlyInAnyOrder("Hard bounce", "Complaint");
+   }
+
+   /*******************************************************************************
+    ** Absent email qbit is no op.
+    *******************************************************************************/
+   @Test
+   void absentEmailQbitIsNoOp() throws Exception
+   {
+      message(1, CrmEmailStatus.SENT, Instant.now());
+      RunBackendStepOutput output = new RunBackendStepOutput();
+      new SyncEmailDeliveryProcess().run(new RunBackendStepInput(), output);
+      assertThat(output.getValueInteger("updatedCount")).isZero();
+      assertThat(new CrmEmailTransport(CrmApi.config()).lookup("key:1")).isEmpty();
+   }
+
+   /*******************************************************************************
+    ** Stale pending members expire without new consent rows.
+    *******************************************************************************/
+   @Test
+   void stalePendingMembersExpireWithoutNewConsentRows() throws Exception
+   {
+      for(int id = 1; id <= 3; id++)
+      {
+         put("crm_email_list_member", new QRecord().withValue("id", id).withValue("emailListId", 1).withValue("email", "a" + id + "@example.test")
+            .withValue("status", id == 3 ? CrmListMemberStatus.SUBSCRIBED.getId() : CrmListMemberStatus.PENDING_CONFIRMATION.getId())
+            .withValue("confirmationSentDate", Instant.now().minus(id == 2 ? 13 : 15, ChronoUnit.DAYS)).withValue("confirmationTokenHash", "hash"));
+      }
+      put("crm_consent_record", new QRecord().withValue("id", 1).withValue("expiryDate", Instant.now().minusSeconds(1)));
+      RunBackendStepOutput output = new RunBackendStepOutput();
+      new ExpireConsentsProcess().run(new RunBackendStepInput(), output);
+      assertThat(output.getValueInteger("expiredPendingCount")).isEqualTo(1);
+      assertThat(output.getValueInteger("expiredConsentCount")).isEqualTo(1);
+      assertThat(GetAction.execute("crm_email_list_member", 1).getValue("confirmationTokenHash")).isNull();
+      assertThat(GetAction.execute("crm_email_list_member", 1).getValueInteger("status")).isEqualTo(CrmListMemberStatus.UNSUBSCRIBED.getId());
+      assertThat(GetAction.execute("crm_email_list_member", 2).getValueString("confirmationTokenHash")).isEqualTo("hash");
+      assertThat(rows("crm_consent_record")).hasSize(1);
+   }
+
+   /*******************************************************************************
+    ** Schedules require scheduler and can be disabled.
+    *******************************************************************************/
+   @Test
+   void schedulesRequireSchedulerAndCanBeDisabled() throws Exception
+   {
+      Map<String, Integer> intervals = Map.of("crm_process_sequence_steps", 300, "crm_calculate_lead_scores", 3600,
+         "crm_sync_email_delivery", 900, "crm_expire_consents", 86400);
+      for(String name : intervals.keySet())
+      {
+         assertThat(QContext.getQInstance().getProcess(name).getSchedule()).isNull();
+      }
+      CrmQBitConfig config = new CrmQBitConfig().withDefaultBackendNameForTables(BACKEND_NAME).withSchedulerName("jobs");
+      var output = new CrmQBitProducer().withQBitConfig(config).produce(new com.kingsrook.qqq.backend.core.model.metadata.QInstance());
+      for(var process : output.getEach(com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData.class))
+      {
+         if(intervals.containsKey(process.getName()))
+         {
+            assertThat(process.getSchedule().getRepeatSeconds()).isEqualTo(intervals.get(process.getName()));
+            assertThat(process.getSchedule().getSchedulerName()).isEqualTo("jobs");
+         }
+      }
+      assertThat(config.getSchedulesEnabled()).isTrue();
+      output = new CrmQBitProducer().withQBitConfig(config.withSchedulesEnabled(false)).produce(new com.kingsrook.qqq.backend.core.model.metadata.QInstance());
+      assertThat(output.getEach(com.kingsrook.qqq.backend.core.model.metadata.processes.QProcessMetaData.class))
+         .allSatisfy(process -> assertThat(process.getSchedule()).isNull());
+   }
+
+   /*******************************************************************************
+    ** Collaboration and alerts use core metadata.
+    *******************************************************************************/
+   @Test
+   void collaborationAndAlertsUseCoreMetadata() throws Exception
+   {
+      for(String table : List.of("crm_contact", "crm_company", "crm_deal", "crm_activity"))
+      {
+         var features = RecordFeaturesMetaData.of(QContext.getQInstance().getTable(table));
+         for(RecordFeature feature : List.of(RecordFeature.TAGS, RecordFeature.COMMENTS, RecordFeature.ATTACHMENTS,
+            RecordFeature.FOLLOW, RecordFeature.TIMELINE, RecordFeature.RECENTS, RecordFeature.FAVORITES))
+         {
+            assertThat(features.getEnabled().get(feature)).isTrue();
+         }
+         assertThat(features.getOwnership().getOwnerFieldName()).isEqualTo("ownerUserId");
+         assertThat(features.getEnabled().get(RecordFeature.TASKS)).isEqualTo("crm_activity".equals(table) ? null : true);
+         assertThat(features.getEnabled().get(RecordFeature.ASSIGNMENT)).isEqualTo("crm_activity".equals(table) ? null : true);
+      }
+      assertThat(AlertsInstanceMetaData.of(QContext.getQInstance()).getAlertTypes()).containsKeys("crm.sequence.failing", "crm.email.unavailable",
+         "crm.lead.assigned", "crm.deal.won", "crm.deal.rotting", "crm.task.due");
+   }
+
+   /*******************************************************************************
+    ** Scoring uses dates incremental changes and daily full pass.
+    *******************************************************************************/
+   @Test
+   void scoringUsesDatesIncrementalChangesAndDailyFullPass() throws Exception
+   {
+      put("crm_contact", contact(1).withValue("lastActivityDate", Instant.now().minus(20, ChronoUnit.DAYS)).withValue("modifyDate", Instant.now().minusSeconds(300)));
+      put("crm_contact", contact(2).withValue("lastActivityDate", Instant.now().minus(2, ChronoUnit.DAYS)).withValue("modifyDate", Instant.now().minusSeconds(300)));
+      rule(1, "lastActivityDate", CrmScoreOperator.DAYS_AGO_GT, "10", -5);
+      rule(2, "lastActivityDate", CrmScoreOperator.DAYS_AGO_LT, "10", 10);
+      assertThat(scores(false).getValueInteger("totalContacts")).isEqualTo(2);
+      assertThat(GetAction.execute("crm_contact", 1).getValueInteger("leadScore")).isEqualTo(-5);
+      assertThat(GetAction.execute("crm_contact", 2).getValueInteger("leadScore")).isEqualTo(10);
+      assertThat(scores(false).getValueInteger("totalContacts")).isZero();
+      CrmRecords.update("crm_contact", new QRecord().withValue("id", 2).withValue("firstName", "Changed"));
+      assertThat(scores(false).getValueInteger("totalContacts")).isEqualTo(1);
+      assertThat(scores(true).getValueInteger("totalContacts")).isEqualTo(2);
+      QRecord state = rows("crm_job_state").getFirst();
+      CrmRecords.update("crm_job_state", state.withValue("lastFullPass", Instant.now().minus(25, ChronoUnit.HOURS)));
+      assertThat(scores(false).getValueInteger("totalContacts")).isEqualTo(2);
+   }
+
+   /*******************************************************************************
+    ** Scoring handles calendar dates and malformed rules.
+    *******************************************************************************/
+   @Test
+   void scoringHandlesCalendarDatesAndMalformedRules() throws Exception
+   {
+      put("crm_contact", contact(1).withValue("lastName", LocalDate.now().minusDays(30).toString()));
+      rule(1, "lastName", CrmScoreOperator.DAYS_AGO_GT, "10", 7);
+      rule(2, "firstName", CrmScoreOperator.DAYS_AGO_LT, "bad", 100);
+      rule(3, "email", CrmScoreOperator.DAYS_AGO_GT, "10", 100);
+      scores(true);
+      assertThat(GetAction.execute("crm_contact", 1).getValueInteger("leadScore")).isEqualTo(7);
+   }
+
+   /*******************************************************************************
+    ** Insert assignment preserves owners and notifies.
+    *******************************************************************************/
+   @Test
+   void insertAssignmentPreservesOwnersAndNotifies() throws Exception
+   {
+      for(CrmAssignableEntity entity : CrmAssignableEntity.values())
+      {
+         put("crm_assignment_rule", new QRecord().withValue("id", entity.getId()).withValue("name", "Assign")
+            .withValue("entityType", entity.getId()).withValue("assignStrategy", CrmAssignStrategy.SPECIFIC_USER.getId())
+            .withValue("assignToUserId", "assigned").withValue("isActive", true).withValue("sortOrder", 1));
+      }
+      QRecord inserted = CrmRecords.insert("crm_contact", new QRecord().withValue("firstName", "New").withValue("lastName", "Contact"));
+      assertThat(GetAction.execute("crm_contact", inserted.getValue("id")).getValueString("ownerUserId")).isEqualTo("assigned");
+      CrmRecords.insert("crm_contact", new QRecord().withValue("firstName", "Already").withValue("lastName", "Owned").withValue("ownerUserId", "explicit"));
+      put("crm_pipeline", new QRecord().withValue("id", 1).withValue("name", "Sales"));
+      put("crm_pipeline_stage", new QRecord().withValue("id", 1).withValue("pipelineId", 1).withValue("name", "Open"));
+      QRecord deal = CrmRecords.insert("crm_deal", new QRecord().withValue("name", "New deal").withValue("pipelineId", 1)
+         .withValue("pipelineStageId", 1).withValue("ownerUserId", "system").withValue("currencyCode", "USD"));
+      assertThat(GetAction.execute("crm_deal", deal.getValue("id")).getValueString("ownerUserId")).isEqualTo("assigned");
+      assertThat(Sink.notifications).hasSize(2).allSatisfy(signal ->
+      {
+         assertThat(signal.getSourceName()).isEqualTo("crm.lead.assigned");
+         assertThat(signal.getAudience()).isEqualTo(NotificationAudience.user("assigned"));
+      });
+   }
+
+   /*******************************************************************************
+    ** Won and rotting notifications target owner and deduplicate stage.
+    *******************************************************************************/
+   @Test
+   void wonAndRottingNotificationsTargetOwnerAndDeduplicateStage() throws Exception
+   {
+      put("crm_pipeline_stage", new QRecord().withValue("id", 1).withValue("name", "Open").withValue("pipelineId", 1).withValue("rotDays", 5));
+      put("crm_pipeline_stage", new QRecord().withValue("id", 2).withValue("name", "Won").withValue("pipelineId", 1).withValue("isClosedWon", true));
+      put("crm_deal", new QRecord().withValue("id", 1).withValue("name", "Old deal").withValue("pipelineId", 1)
+         .withValue("pipelineStageId", 1).withValue("ownerUserId", "owner").withValue("stageEnteredDate", Instant.now().minus(10, ChronoUnit.DAYS)));
+      CrmDealNotifications.checkRotting();
+      CrmDealNotifications.checkRotting();
+      assertThat(Sink.notifications).singleElement().satisfies(signal -> assertThat(signal.getSourceKey()).isEqualTo("deal:1:stage:1"));
+      CrmRecords.update("crm_deal", new QRecord().withValue("id", 1).withValue("pipelineStageId", 2));
+      assertThat(Sink.notifications).hasSize(2);
+      assertThat(Sink.notifications.getLast().getSourceName()).isEqualTo("crm.deal.won");
+      assertThat(Sink.notifications.getLast().getAudience()).isEqualTo(NotificationAudience.user("owner"));
+      CrmRecords.update("crm_deal", new QRecord().withValue("id", 1).withValue("pipelineStageId", 2));
+      CrmDealNotifications.checkRotting();
+      assertThat(Sink.notifications).hasSize(2);
+   }
+
+
+   /*******************************************************************************
+    ** Company loading scales with pages, not contacts or rules.
+    *******************************************************************************/
+   @Test
+   void scoringLoadsCompaniesOncePerPage() throws Exception
+   {
+      put("crm_company", new QRecord().withValue("id", 1).withValue("name", "Example"));
+      for(int id = 1; id <= 201; id++)
+      {
+         put("crm_contact", contact(id).withValue("companyId", 1));
+      }
+      rule(1, "company.name", CrmScoreOperator.EQUALS, "Example", 3);
+      rule(2, "company.name", CrmScoreOperator.IS_SET, null, 2);
+      CompanyReads.count = 0;
+      QContext.getQInstance().getTable("crm_company").withCustomizer(
+         com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers.POST_QUERY_RECORD, new QCodeReference(CompanyReads.class));
+      assertThat(scores(true).getValueInteger("updatedCount")).isEqualTo(201);
+      // Two explicit page loads, plus at most two core audit-label translations.
+      assertThat(CompanyReads.count).isBetween(2, 4);
+      assertThat(GetAction.execute("crm_contact", 201).getValueInteger("leadScore")).isEqualTo(5);
+   }
+
+   /*******************************************************************************
+    ** Failed scoring must leave the successful checkpoint unchanged.
+    *******************************************************************************/
+   @Test
+   void scoringFailureDoesNotAdvanceCheckpoint() throws Exception
+   {
+      contact(1);
+      scores(true);
+      Instant checkpoint = rows("crm_job_state").getFirst().getValueInstant("lastSuccess");
+      rule(1, "firstName", CrmScoreOperator.IS_SET, null, 1);
+      QContext.getQInstance().getTable("crm_contact").withCustomizer(
+         com.kingsrook.qqq.backend.core.actions.customizers.TableCustomizers.PRE_UPDATE_RECORD, new QCodeReference(RejectScore.class));
+      assertThrows(QException.class, () -> scores(true));
+      assertThat(rows("crm_job_state").getFirst().getValueInstant("lastSuccess")).isEqualTo(checkpoint);
+   }
+
+   /*******************************************************************************
+    ** Retry repairs a missing activity without sending the persisted message again.
+    *******************************************************************************/
+   @Test
+   void retryRepairsActivityAfterPartialRecording() throws Exception
+   {
+      QRecord contact = contact(1);
+      put("crm_email_message", new QRecord().withValue("id", 1).withValue("contactId", 1).withValue("subject", "Already sent")
+         .withValue("idempotencyKey", "crm:email:1:retry").withValue("status", CrmEmailStatus.SENT.getId()));
+      CrmEmails.send(transport, contact, null, "Already sent", "body", "email", "1:retry", null);
+      assertThat(transport.sends).isZero();
+      assertActivity("EMAIL");
+      assertThat(GetAction.execute("crm_email_message", 1).getValue("activityId")).isNotNull();
+   }
+
+   /*******************************************************************************
+    ** Count actual backend company queries.
+    *******************************************************************************/
+   public static class CompanyReads extends com.kingsrook.qqq.backend.core.actions.customizers.AbstractPostQueryCustomizer
+   {
+      private static int count;
+
+      @Override
+      public List<QRecord> apply(List<QRecord> records)
+      {
+         count++;
+         return (records);
+      }
+   }
+
+   /*******************************************************************************
+    ** Return a record-level error to exercise checked background writes.
+    *******************************************************************************/
+   public static class RejectScore extends com.kingsrook.qqq.backend.core.actions.customizers.AbstractPreUpdateCustomizer
+   {
+      @Override
+      public List<QRecord> apply(List<QRecord> records)
+      {
+         records.forEach(row -> row.addError(new com.kingsrook.qqq.backend.core.model.statusmessages.BadInputStatusMessage("Rejected score")));
+         return (records);
+      }
+   }
+
+   /*******************************************************************************
+    ** Send action with a local fake.
+    *******************************************************************************/
+   private CrmAction.Load load()
+   {
+      return (new CrmAction.Load()
+      {
+         @Override
+         protected CrmEmailTransport emailTransport()
+         {
+            return (transport);
+         }
+      });
+   }
+
+   /*******************************************************************************
+    ** Sequence runner with a local fake.
+    *******************************************************************************/
+   private void sequence() throws QException
+   {
+      new ProcessSequenceStepsProcess()
+      {
+         @Override
+         protected CrmEmailTransport emailTransport()
+         {
+            return (transport);
+         }
+      }.run(new RunBackendStepInput(), new RunBackendStepOutput());
+   }
+
+   /*******************************************************************************
+    ** Sync with a local fake.
+    *******************************************************************************/
+   private void sync() throws QException
+   {
+      new SyncEmailDeliveryProcess()
+      {
+         @Override
+         protected CrmEmailTransport emailTransport()
+         {
+            return (transport);
+         }
+      }.run(new RunBackendStepInput(), new RunBackendStepOutput());
+   }
+
+   /*******************************************************************************
+    ** Run score work using normal QQQ actions.
+    *******************************************************************************/
+   private RunBackendStepOutput scores(boolean full) throws QException
+   {
+      RunBackendStepOutput output = new RunBackendStepOutput();
+      new CalculateLeadScoresProcess().run(new RunBackendStepInput().addValue("fullRecalc", full), output);
+      return (output);
+   }
+
+   /*******************************************************************************
+    ** Contact fixture.
+    *******************************************************************************/
+   private QRecord contact(int id) throws QException
+   {
+      QRecord row = new QRecord().withValue("id", id).withValue("firstName", "Alice").withValue("lastName", "Smith")
+         .withValue("email", "alice" + id + "@example.test").withValue("ownerUserId", "owner");
+      put("crm_contact", row);
+      return (row);
+   }
+
+   /*******************************************************************************
+    ** Sequence fixtures use enum identifiers.
+    *******************************************************************************/
+   private void seedSequence(boolean active, boolean eligible) throws QException
+   {
+      contact(1);
+      put("crm_email_sequence", new QRecord().withValue("id", 1).withValue("name", "Sequence").withValue("isActive", active).withValue("totalSteps", 1));
+      put("crm_email_template", new QRecord().withValue("id", 1).withValue("subject", "Hello {{contact.firstName}}").withValue("bodyText", "Welcome"));
+      put("crm_sequence_step", new QRecord().withValue("id", 1).withValue("sequenceId", 1).withValue("stepNumber", 1)
+         .withValue("stepType", CrmSequenceStepType.EMAIL.getId()).withValue("emailTemplateId", 1));
+      put("crm_sequence_enrollment", new QRecord().withValue("id", 1).withValue("sequenceId", 1).withValue("contactId", 1)
+         .withValue("status", CrmEnrollmentStatus.ACTIVE.getId()).withValue("currentStepNumber", 0).withValue("failureCount", 0)
+         .withValue("nextStepDate", Instant.now().minusSeconds(60)));
+      if(eligible)
+      {
+         put("crm_consent_record", new QRecord().withValue("id", 1).withValue("contactId", 1).withValue("consentType", CrmConsentType.EMAIL.getId())
+            .withValue("status", CrmConsentStatus.GRANTED.getId()).withValue("consentDate", Instant.now()));
+      }
+   }
+
+   /*******************************************************************************
+    ** Transport-linked message fixture.
+    *******************************************************************************/
+   private void message(int id, CrmEmailStatus status, Instant created) throws QException
+   {
+      put("crm_email_message", new QRecord().withValue("id", id).withValue("contactId", id).withValue("subject", "Test")
+         .withValue("idempotencyKey", "key:" + id).withValue("status", status.getId()).withValue("createDate", created));
+   }
+
+   /*******************************************************************************
+    ** Score rule fixture.
+    *******************************************************************************/
+   private void rule(int id, String field, CrmScoreOperator operator, String expected, int points) throws QException
+   {
+      put("crm_lead_score_rule", new QRecord().withValue("id", id).withValue("name", "Rule " + id).withValue("fieldPath", field)
+         .withValue("operator", operator.getId()).withValue("fieldValue", expected).withValue("scoreAdjustment", points).withValue("isActive", true));
+   }
+
+   /*******************************************************************************
+    ** Assert the activity's stable code.
+    *******************************************************************************/
+   private void assertActivity(String code) throws QException
+   {
+      QRecord activity = rows("crm_activity").getFirst();
+      assertThat(GetAction.execute("crm_activity_type", activity.getValue("activityTypeId")).getValueString("code")).isEqualTo(code);
+   }
+
+   /*******************************************************************************
+    ** Insert isolated fixture data.
+    *******************************************************************************/
+   private void put(String table, QRecord row) throws QException
+   {
+      if(row.getValue("id") != null && GetAction.execute(table, row.getValue("id")) != null)
+      {
+         MemoryRecordStore.getInstance().update(new com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput(table).withRecord(row), true);
+      }
+      else
+      {
+         MemoryRecordStore.getInstance().insert(new InsertInput(table).withRecord(row), true);
+      }
+   }
+
+   /*******************************************************************************
+    ** Query in the current session.
+    *******************************************************************************/
+   private List<QRecord> rows(String table) throws QException
+   {
+      return (new QueryAction().execute(new QueryInput(table)).getRecords());
+   }
+
+   /*******************************************************************************
+    ** Fake transport with independent send and delivery controls.
+    *******************************************************************************/
+   private static class FakeTransport extends CrmEmailTransport
+   {
+      private boolean ready = true;
+      private boolean fail;
+      private boolean marketing;
+      private int sends;
+      private String key;
+      private String subject;
+      private String body;
+      private final Map<String, Delivery> deliveries = new HashMap<>();
+      private final List<String> lookups = new ArrayList<>();
+
+      /*******************************************************************************
+       ** No external provider is installed.
+       *******************************************************************************/
+      FakeTransport()
+      {
+         super(new CrmQBitConfig());
+      }
+
+      @Override
+      public CrmReadiness readiness()
+      {
+         return (ready ? CrmReadiness.QBIT_EMAIL : CrmReadiness.NOT_CONFIGURED);
+      }
+
+      @Override
+      public Delivery sendMessage(String purpose, String id, Integer contactId, String address, String subject, String body, boolean marketing) throws QException
+      {
+         if(fail)
+         {
+            throw (new QException("Fake transport failure"));
+         }
+         sends++;
+         key = "crm:" + purpose + ":" + id;
+         this.subject = subject;
+         this.body = body;
+         this.marketing = marketing;
+         return (new Delivery("provider-1", CrmEmailStatus.QUEUED, null, null, null, null, null));
+      }
+
+      @Override
+      public Optional<Delivery> lookup(String key)
+      {
+         lookups.add(key);
+         return (Optional.ofNullable(deliveries.get(key)));
+      }
+   }
+
+   /*******************************************************************************
+    ** Capture the core dispatch without an alerts backend.
+    *******************************************************************************/
+   public static class Sink extends LoggingAlertSink
+   {
+      private static final List<NotificationSignal> notifications = new ArrayList<>();
+      private static final List<AlertSignal> alerts = new ArrayList<>();
+      private static final List<AlertResolution> resolutions = new ArrayList<>();
+
+      @Override
+      public void notify(NotificationSignal signal)
+      {
+         notifications.add(signal);
+      }
+
+      @Override
+      public void raise(AlertSignal signal)
+      {
+         alerts.add(signal);
+      }
+
+      @Override
+      public void resolve(AlertResolution resolution)
+      {
+         resolutions.add(resolution);
+      }
+   }
+}

src/test/java/com/kingsrook/qbits/crm/TokenRequiredAuthenticationModule.java

@@ -0,0 +1,72 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2025.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm;
+
+
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import com.kingsrook.qqq.backend.core.exceptions.QAuthenticationException;
+import com.kingsrook.qqq.backend.core.model.metadata.QInstance;
+import com.kingsrook.qqq.backend.core.model.session.QSession;
+import com.kingsrook.qqq.backend.core.model.session.QSystemUserSession;
+import com.kingsrook.qqq.backend.core.modules.authentication.QAuthenticationModuleInterface;
+
+
+/*******************************************************************************
+ ** Test authentication module that behaves like the token-based core modules
+ ** (OAuth2, Auth0): a QSystemUserSession is always valid, a session it created
+ ** is valid, and any other session has no token and fails validation with the
+ ** same message the OAuth2 module produces (JWTDecodeException: The token is
+ ** null).
+ *******************************************************************************/
+public class TokenRequiredAuthenticationModule implements QAuthenticationModuleInterface
+{
+   private static final Set<String> ISSUED = ConcurrentHashMap.newKeySet();
+
+
+
+   /*******************************************************************************
+    ** Issue a session that carries a token.
+    *******************************************************************************/
+   @Override
+   public QSession createSession(QInstance qInstance, Map<String, String> context) throws QAuthenticationException
+   {
+      QSession session = new QSession();
+      ISSUED.add(session.getUuid());
+      return (session);
+   }
+
+
+
+   /*******************************************************************************
+    ** Accept the system user and issued sessions; reject tokenless sessions.
+    *******************************************************************************/
+   @Override
+   public boolean isSessionValid(QInstance instance, QSession session)
+   {
+      if(session instanceof QSystemUserSession || ISSUED.contains(session.getUuid()))
+      {
+         return (true);
+      }
+      throw (new IllegalStateException("The token is null"));
+   }
+}

src/test/java/com/kingsrook/qbits/crm/actions/CrmActionsTest.java

@@ -133,7 +133,7 @@ class CrmActionsTest extends BaseTest
    void metadataIsComplete()
    {
       assertThat(CrmActions.ACTIONS).hasSize(28);
-      assertThat(QContext.getQInstance().getProcesses().keySet().stream().filter(name -> !name.contains("."))).hasSize(30);
+      assertThat(QContext.getQInstance().getProcesses().keySet().stream().filter(name -> !name.contains("."))).hasSize(32);
       for(CrmActions.Action action : CrmActions.ACTIONS)
       {
          QProcessMetaData process = QContext.getQInstance().getProcess(action.name());
@@ -154,7 +154,7 @@ class CrmActionsTest extends BaseTest
             assertThat(process.getMaxInputRecords()).isEqualTo(2);
          }
       }
-      for(String name : List.of("crm_process_sequence_steps", "crm_calculate_lead_scores"))
+      for(String name : List.of("crm_process_sequence_steps", "crm_calculate_lead_scores", "crm_sync_email_delivery", "crm_expire_consents"))
       {
          assertThat(QContext.getQInstance().getProcess(name).getTableName()).isNull();
       }
@@ -386,7 +386,9 @@ class CrmActionsTest extends BaseTest
          put("crm_contact", new QRecord().withValue("id", 10 + i * 2).withValue("lastName", "Contact").withValue("ownerUserId", "original"));
       }
       PageObserver.sizes.clear();
-      QContext.getQInstance().getTable("crm_contact").withCustomizer(TableCustomizers.POST_QUERY_RECORD, new QCodeReference(PageObserver.class));
+      QContext.getQInstance().getTable("crm_contact").getCustomizers().remove(TableCustomizers.POST_QUERY_RECORD.getRole());
+      QContext.getQInstance().getTable("crm_contact").withCustomizer(TableCustomizers.POST_QUERY_RECORD, com.kingsrook.qqq.backend.core.actions.customizers.MultiCustomizer.of(
+            new QCodeReference(com.kingsrook.qbits.crm.core.customizers.ContactLabelCustomizer.class), new QCodeReference(PageObserver.class)));
       RunProcessOutput result = new RunProcessAction().execute(new RunProcessInput().withProcessName("crm_calculate_lead_scores"));
       assertThat(result.getValues().get("totalContacts")).isEqualTo(405);
       assertThat(result.getValues().get("updatedCount")).isEqualTo(405);

src/test/java/com/kingsrook/qbits/crm/api/CrmApisTest.java

@@ -99,6 +99,23 @@ public class CrmApisTest extends BaseTest
 
    }
 
+   /*******************************************************************************
+    ** Email-only intake preserves absent names and never assigns the service user.
+    *******************************************************************************/
+   @Test
+   void emailOnlyIntakeHasNoOwner() throws Exception
+   {
+      QContext.getQSession().setIdReference("site-api-system");
+      CrmFormResult result = intake.submitForm(new CrmFormRequest("contact", FormType.CONTACT, null, " ", "only@example.test",
+         null, null, "Hello", false, "Reply", null, null, null, null, null, null, null, null, null));
+      QRecord contact = CrmStore.asUser().get("crm_contact", result.contactId());
+      assertThat(contact.getValue("firstName")).isNull();
+      assertThat(contact.getValue("lastName")).isNull();
+      assertThat(contact.getValue("ownerUserId")).isNull();
+      assertThat(contact.getRecordLabel()).isEqualTo("only@example.test");
+   }
+
+
    /*******************************************************************************
     ** Form preserves first touch and never grants implicit marketing consent.
     *******************************************************************************/
@@ -530,7 +547,7 @@ public class CrmApisTest extends BaseTest
       assertThat(CrmStore.trusted().by("crm_contact", "email", "subscriber@example.test").get(0).getValueString("ownerUserId")).isEqualTo("sales-0");
       QContext.getQSession().setIdReference("named-owner");
       Integer owned = intake.submitForm(form("owned@example.test", false, "owned")).contactId();
-      assertThat(CrmStore.trusted().get("crm_contact", owned).getValueString("ownerUserId")).isEqualTo("named-owner");
+      assertThat(CrmStore.trusted().get("crm_contact", owned).getValueString("ownerUserId")).isEqualTo("sales-1");
       CrmStore.trusted().update("crm_contact", new QRecord().withValue("id", first.contactId()).withValue("ownerUserId", "system"));
       intake.submitForm(form("first@example.test", false, "existing-unowned"));
       assertThat(CrmStore.trusted().get("crm_contact", first.contactId()).getValueString("ownerUserId")).isEqualTo("system");

src/test/java/com/kingsrook/qbits/crm/api/CrmDefaultsBehaviorTest.java

@@ -0,0 +1,157 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.api;
+
+
+import java.math.BigDecimal;
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
+import java.sql.Statement;
+import java.util.List;
+import com.kingsrook.qbits.crm.BaseTest;
+import com.kingsrook.qbits.crm.CrmDefaultsChangelogTest;
+import com.kingsrook.qbits.crm.deals.processes.ConvertLeadProcess;
+import com.kingsrook.qbits.crm.email.CrmEmailTransport;
+import com.kingsrook.qbits.crm.widgets.CrmSetupStatus;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepInput;
+import com.kingsrook.qqq.backend.core.model.actions.processes.RunBackendStepOutput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** The shipped defaults change behavior: with exactly the rows the changelog
+ ** inserts (applied to H2, then copied into the test backend), Convert lead
+ ** works and moves the contact to Opportunity, intake gives a new lead the Lead
+ ** stage, and the Setup card has nothing left to do.
+ *******************************************************************************/
+class CrmDefaultsBehaviorTest extends BaseTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void seededRowsMakeTheCrmWork() throws Exception
+   {
+      loadSeededRows();
+
+      ////////////////////////////////////////////////////////////////
+      // intake: a new web lead is assigned the seeded "Lead" stage //
+      ////////////////////////////////////////////////////////////////
+      CrmIntakeApi intake = new CrmIntakeApi(CrmApi.config(), new CrmEmailTransport(CrmApi.config()));
+      Integer contactId = intake.submitForm(new CrmFormRequest("contact", FormType.CONTACT, "Ada", "Lovelace", "ada@example.test", "555-0100",
+         "Example", "Hello", false, "Reply", "search", "organic", "c", "banner", "crm", "https://example.test/form", "https://search.example.test",
+         "a".repeat(64), "b".repeat(64))).contactId();
+      QRecord lead = CrmStore.asUser().get("crm_contact", contactId);
+      Integer leadStageId = CrmStore.asUser().by("crm_lifecycle_stage", "name", "Lead").getFirst().getValueInteger("id");
+      assertThat(lead.getValueInteger("lifecycleStageId")).isEqualTo(leadStageId);
+
+      ////////////////////////////////////////////////////////////////////////////////
+      // Convert lead: finds the default pipeline and its first stage, and moves the //
+      // contact to the seeded "Opportunity" stage                                  //
+      ////////////////////////////////////////////////////////////////////////////////
+      RunBackendStepInput input = new RunBackendStepInput();
+      input.setProcessName(ConvertLeadProcess.NAME);
+      input.addValue("contactId", contactId);
+      input.addValue("dealName", "Ada deal");
+      input.addValue("dealAmount", new BigDecimal("1000"));
+      RunBackendStepOutput output = runBusinessStep(input);
+      QRecord deal = CrmStore.asUser().get("crm_deal", output.getValueInteger("dealId"));
+      assertThat(deal).isNotNull();
+      QRecord firstStage = CrmStore.asUser().by("crm_pipeline_stage", "name", "Qualification").getFirst();
+      assertThat(deal.getValueInteger("pipelineStageId")).isEqualTo(firstStage.getValueInteger("id"));
+      Integer opportunityId = CrmStore.asUser().by("crm_lifecycle_stage", "name", "Opportunity").getFirst().getValueInteger("id");
+      assertThat(CrmStore.asUser().get("crm_contact", contactId).getValueInteger("lifecycleStageId")).isEqualTo(opportunityId);
+      assertThat(deal.getValueBigDecimal("amountInBaseCurrency")).isEqualByComparingTo("1000");
+
+      ///////////////////////////////////////////////////////////////
+      // setup card: nothing left to do for the five tracked items //
+      ///////////////////////////////////////////////////////////////
+      List<CrmSetupStatus.Item> items = CrmSetupStatus.load();
+      assertThat(items).extracting(CrmSetupStatus.Item::state).doesNotContain(CrmSetupStatus.State.TODO);
+      assertThat(items).filteredOn(item -> !item.label().equals("Email delivery")).extracting(CrmSetupStatus.Item::state).containsOnly(CrmSetupStatus.State.OK);
+   }
+
+
+
+   /*******************************************************************************
+    ** Apply the defaults to a fresh H2 schema and insert every row it created
+    ** into the test backend, preserving ids.
+    *******************************************************************************/
+   private void loadSeededRows() throws Exception
+   {
+      try(Connection connection = CrmDefaultsChangelogTest.freshSchema())
+      {
+         CrmDefaultsChangelogTest.runChangelog(connection, false);
+         for(String table : CrmDefaultsChangelogTest.SEEDED_TABLES)
+         {
+            try(Statement statement = connection.createStatement(); ResultSet rs = statement.executeQuery("SELECT * FROM " + table + " ORDER BY id"))
+            {
+               ResultSetMetaData meta = rs.getMetaData();
+               while(rs.next())
+               {
+                  QRecord record = new QRecord();
+                  for(int i = 1; i <= meta.getColumnCount(); i++)
+                  {
+                     String column = meta.getColumnLabel(i).toLowerCase();
+                     if(column.equals("create_date") || column.equals("modify_date") || rs.getObject(i) == null)
+                     {
+                        continue;
+                     }
+                     record.setValue(camel(column), (java.io.Serializable) rs.getObject(i));
+                  }
+                  var result = new InsertAction().execute(new InsertInput(table).withRecord(record));
+                  assertThat(result.getRecords().getFirst().getErrors()).as(table).isNullOrEmpty();
+               }
+            }
+         }
+      }
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private static String camel(String snake)
+   {
+      StringBuilder sb    = new StringBuilder();
+      boolean       upper = false;
+      for(char c : snake.toCharArray())
+      {
+         if(c == '_')
+         {
+            upper = true;
+         }
+         else
+         {
+            sb.append(upper ? Character.toUpperCase(c) : c);
+            upper = false;
+         }
+      }
+      return (sb.toString());
+   }
+
+}

src/test/java/com/kingsrook/qbits/crm/core/model/ContactTest.java

@@ -127,7 +127,7 @@ class ContactTest extends BaseTest
       ///////////////////////////////////
       // verify T1 identity section    //
       ///////////////////////////////////
-      assertThat(table.getSections().get(0).getFieldNames()).contains("id", "firstName", "lastName", "email", "phone");
+      assertThat(table.getSections().get(0).getFieldNames()).contains("firstName", "lastName", "email", "phone");
    }
 
 

src/test/java/com/kingsrook/qbits/crm/core/model/CurrencyRateDateTest.java

@@ -0,0 +1,68 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.core.model;
+
+
+import java.math.BigDecimal;
+import java.time.Instant;
+import com.kingsrook.qbits.crm.BaseTest;
+import com.kingsrook.qqq.backend.core.actions.tables.GetAction;
+import com.kingsrook.qqq.backend.core.actions.tables.InsertAction;
+import com.kingsrook.qqq.backend.core.actions.tables.UpdateAction;
+import com.kingsrook.qqq.backend.core.model.actions.tables.insert.InsertInput;
+import com.kingsrook.qqq.backend.core.model.actions.tables.update.UpdateInput;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+
+
+/*******************************************************************************
+ ** crm_currency.rateLastUpdatedDate says when the exchange rate was last set or
+ ** changed: stamped on insert, moved by a changed rate, left alone by an edit
+ ** that does not touch the rate.
+ *******************************************************************************/
+class CurrencyRateDateTest extends BaseTest
+{
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   @Test
+   void stampsOnInsertAndOnlyMovesWhenTheRateChanges() throws Exception
+   {
+      Instant before = Instant.now().minusSeconds(1);
+      Integer id = new InsertAction().execute(new InsertInput("crm_currency").withRecord(new QRecord()
+         .withValue("currencyCode", "EUR").withValue("name", "Euro").withValue("exchangeRateToBase", new BigDecimal("1.10"))))
+         .getRecords().getFirst().getValueInteger("id");
+      Instant stamped = GetAction.execute("crm_currency", id).getValueInstant("rateLastUpdatedDate");
+      assertThat(stamped).as("insert stamps the date").isAfter(before);
+
+      Thread.sleep(20);
+      new UpdateAction().execute(new UpdateInput("crm_currency").withRecord(new QRecord().withValue("id", id).withValue("name", "Euro (EU)")));
+      assertThat(GetAction.execute("crm_currency", id).getValueInstant("rateLastUpdatedDate")).as("a rename leaves the date").isEqualTo(stamped);
+
+      new UpdateAction().execute(new UpdateInput("crm_currency").withRecord(new QRecord().withValue("id", id).withValue("exchangeRateToBase", new BigDecimal("1.100000"))));
+      assertThat(GetAction.execute("crm_currency", id).getValueInstant("rateLastUpdatedDate")).as("the same rate leaves the date").isEqualTo(stamped);
+
+      new UpdateAction().execute(new UpdateInput("crm_currency").withRecord(new QRecord().withValue("id", id).withValue("exchangeRateToBase", new BigDecimal("1.25"))));
+      assertThat(GetAction.execute("crm_currency", id).getValueInstant("rateLastUpdatedDate")).as("a new rate moves the date").isAfter(stamped);
+   }
+
+}

src/test/java/com/kingsrook/qbits/crm/deals/customizers/DealInitializationCustomizerTest.java

@@ -119,6 +119,30 @@ class DealInitializationCustomizerTest extends BaseTest
 
 
 
+   /*******************************************************************************
+    ** Lost-stage inserts close immediately while imported dates are preserved.
+    *******************************************************************************/
+   @Test
+   void closedStageDates() throws QException
+   {
+      Integer pipeline = insertPipeline("Closed imports");
+      Integer stage = new InsertAction().execute(new InsertInput(PipelineStage.TABLE_NAME).withRecordEntity(new PipelineStage()
+         .withPipelineId(pipeline).withName("Lost").withSortOrder(1).withProbabilityPct(0).withIsClosedLost(true)))
+         .getRecords().getFirst().getValueInteger("id");
+      Deal lost = new Deal(GetAction.execute(Deal.TABLE_NAME, insertDeal("Lost", pipeline, stage, BigDecimal.TEN)));
+      assertEquals(java.time.LocalDate.now(java.time.ZoneOffset.UTC), lost.getActualCloseDate());
+      assertNotNull(lost.getStageEnteredDate());
+      java.time.LocalDate closeDate = java.time.LocalDate.of(2025, 1, 2);
+      java.time.Instant entered = java.time.Instant.parse("2025-01-01T10:00:00Z");
+      Integer imported = new InsertAction().execute(new InsertInput(Deal.TABLE_NAME).withRecordEntity(new Deal()
+         .withName("Imported").withPipelineId(pipeline).withPipelineStageId(stage).withActualCloseDate(closeDate).withStageEnteredDate(entered)))
+         .getRecords().getFirst().getValueInteger("id");
+      Deal saved = new Deal(GetAction.execute(Deal.TABLE_NAME, imported));
+      assertEquals(closeDate, saved.getActualCloseDate());
+      assertEquals(entered, saved.getStageEnteredDate());
+   }
+
+
    /////////////////////////////////////////////////////////////////////////////
    // Helper methods                                                          //
    /////////////////////////////////////////////////////////////////////////////

src/test/java/com/kingsrook/qbits/crm/email/processes/ProcessSequenceStepsProcessTest.java

@@ -60,10 +60,10 @@ class ProcessSequenceStepsProcessTest extends BaseTest
 {
 
    /*******************************************************************************
-    ** Email step should create an activity record.
+    ** Email without recorded consent pauses without creating a fake activity.
     *******************************************************************************/
    @Test
-   void testEmailStepCreatesActivity() throws QException
+   void testEmailStepRequiresConsent() throws QException
    {
       insertActivityType("Email");
       insertActivityType("Task");
@@ -91,8 +91,7 @@ class ProcessSequenceStepsProcessTest extends BaseTest
       QueryOutput activityQuery = new QueryAction().execute(
          new QueryInput(Activity.TABLE_NAME));
 
-      assertThat(activityQuery.getRecords()).isNotEmpty();
-      assertThat(activityQuery.getRecords().get(0).getValueString("subject")).contains("Sequence email");
+      assertThat(activityQuery.getRecords()).isEmpty();
 
       /////////////////////////////////////////////
       // verify enrollment was advanced          //
@@ -101,7 +100,8 @@ class ProcessSequenceStepsProcessTest extends BaseTest
          new QueryInput(SequenceEnrollment.TABLE_NAME));
 
       SequenceEnrollment enrollment = new SequenceEnrollment(enrollmentQuery.getRecords().get(0));
-      assertEquals(1, enrollment.getCurrentStepNumber());
+      assertEquals(0, enrollment.getCurrentStepNumber());
+      assertEquals(CrmEnrollmentStatus.PAUSED.getId(), enrollment.getStatus());
    }
 
 
@@ -142,10 +142,10 @@ class ProcessSequenceStepsProcessTest extends BaseTest
 
 
    /*******************************************************************************
-    ** After 3 failures, enrollment should be marked as FAILED.
+    ** Opt-out pauses an enrollment without counting it as a delivery failure.
     *******************************************************************************/
    @Test
-   void testFailureCounting() throws QException
+   void testOptOutPausesWithoutCountingFailure() throws QException
    {
       Integer sequenceId = insertSequence("Fail Seq", true, 2, false);
       Integer contactId = insertContact("Carol", "Fail", true); // doNotEmail = true
@@ -181,8 +181,8 @@ class ProcessSequenceStepsProcessTest extends BaseTest
          new QueryInput(SequenceEnrollment.TABLE_NAME));
 
       SequenceEnrollment enrollment = new SequenceEnrollment(enrollmentQuery.getRecords().get(0));
-      assertEquals(CrmEnrollmentStatus.FAILED.getId(), enrollment.getStatus());
-      assertEquals(3, enrollment.getFailureCount());
+      assertEquals(CrmEnrollmentStatus.PAUSED.getId(), enrollment.getStatus());
+      assertEquals(2, enrollment.getFailureCount());
       assertThat(enrollment.getLastFailureMessage()).isNotNull();
    }
 

src/test/java/com/kingsrook/qbits/crm/widgets/CrmContactTimelineWidgetTest.java

@@ -64,6 +64,26 @@ class CrmContactTimelineWidgetTest extends BaseTest
    }
 
 
+   /*******************************************************************************
+    ** Session zones observe DST; missing or invalid zones fall back to UTC.
+    *******************************************************************************/
+   @Test
+   void readableDates()
+   {
+      Instant time = Instant.parse("2026-10-14T20:19:01.142263Z");
+      assertThat(CrmContactTimelineRenderer.formatDate(time)).isEqualTo("Oct 14, 2026 8:19 PM");
+      QContext.getQSession().setValue("UserTimezone", "America/Chicago");
+      assertThat(CrmContactTimelineRenderer.formatDate(time)).isEqualTo("Oct 14, 2026 3:19 PM");
+      assertThat(CrmContactTimelineRenderer.formatDate(Instant.parse("2026-01-14T20:19:00Z"))).isEqualTo("Jan 14, 2026 2:19 PM");
+      QContext.getQSession().setValue("UserTimezone", "invalid");
+      assertThat(CrmContactTimelineRenderer.formatDate(time)).isEqualTo("Oct 14, 2026 8:19 PM");
+      QContext.getQSession().setValue("UserTimezone", "");
+      QContext.getQSession().setValue("UserTimezoneOffsetMinutes", "120");
+      assertThat(CrmContactTimelineRenderer.formatDate(time)).isEqualTo("Oct 14, 2026 10:19 PM");
+      assertThat(CrmContactTimelineRenderer.formatDate(null)).isEmpty();
+   }
+
+
    /*******************************************************************************
     ** Missing and nonexistent parent ids never query all contacts' histories.
     *******************************************************************************/

src/test/java/com/kingsrook/qbits/crm/widgets/CrmHomeWidgetsTest.java

@@ -82,6 +82,54 @@ class CrmHomeWidgetsTest extends BaseTest
    }
 
 
+   /*******************************************************************************
+    ** Whole and fractional amounts retain grouping without artificial decimals.
+    *******************************************************************************/
+   @Test
+   void amountFormatting()
+   {
+      assertThat(CrmHomeRenderer.formatAmount(new BigDecimal("72000.000000"))).isEqualTo("72,000");
+      assertThat(CrmHomeRenderer.formatAmount(new BigDecimal("1234.560000"))).isEqualTo("1,234.56");
+      assertThat(CrmHomeRenderer.formatAmount(new BigDecimal("-1234.005"))).isEqualTo("-1,234.005");
+      assertThat(CrmHomeRenderer.formatAmount(null)).isEqualTo("0");
+   }
+
+
+   /*******************************************************************************
+    ** A direct won-stage insert participates in actual-close reporting immediately.
+    *******************************************************************************/
+   @Test
+   void directWonInsert() throws Exception
+   {
+      seedStages();
+      seed("crm_currency", new QRecord().withValue("currencyCode", "USD").withValue("isBaseCurrency", true));
+      var inserted = new com.kingsrook.qqq.backend.core.actions.tables.InsertAction().execute(new InsertInput("crm_deal")
+         .withRecord(new QRecord().withValue("name", "Direct win").withValue("pipelineId", 1).withValue("pipelineStageId", 2)
+            .withValue("amount", new BigDecimal("72000")).withValue("expectedCloseDate", LocalDate.now().plusYears(1))));
+      assertThat(inserted.getRecords().getFirst().getErrors()).isNullOrEmpty();
+      var deal = com.kingsrook.qqq.backend.core.actions.tables.GetAction.execute("crm_deal", inserted.getRecords().getFirst().getValue("id"));
+      assertThat(deal.getValue("ownerUserId")).isNull();
+      assertThat(deal.getValueLocalDate("actualCloseDate")).isEqualTo(LocalDate.now(ZoneOffset.UTC));
+      assertThat(deal.getValueInstant("stageEnteredDate")).isNotNull();
+      assertThat(((StatisticsData) render("crm_won_month")).getCount()).isEqualTo("USD 72,000");
+      TableData leaderboard = (TableData) render("crm_sales_leaderboard");
+      assertCell(leaderboard, 0, "first", "Unassigned");
+      assertCell(leaderboard, 0, "second", "1");
+      assertCell(leaderboard, 0, "third", "72,000");
+   }
+
+
+   /*******************************************************************************
+    ** A partial submission name uses the email to retain identifying context.
+    *******************************************************************************/
+   @Test
+   void partialLeadName() throws Exception
+   {
+      seed("crm_form_submission", new QRecord().withValue("firstName", "Lee").withValue("email", "lee@example.test"));
+      assertCell((TableData) render("crm_recent_web_leads"), 0, "first", "lee@example.test");
+   }
+
+
    /*******************************************************************************
     ** Empty data renders zero statistics, six months and no goals card.
     *******************************************************************************/
@@ -92,7 +140,7 @@ class CrmHomeWidgetsTest extends BaseTest
       {
          assertStatistic(name, "0");
       }
-      for(String name : CrmHomeWidgets.HOME.subList(1, CrmHomeWidgets.HOME.size()))
+      for(String name : CrmHomeWidgets.HOME.subList(1, CrmHomeWidgets.HOME.size()).stream().filter(name -> !name.equals("crm_setup")).toList())
       {
          TableData data = (TableData) render(name);
          assertThat(data.getRows()).hasSize(name.equals("crm_deal_forecast") ? 6 : 0);
@@ -119,16 +167,16 @@ class CrmHomeWidgetsTest extends BaseTest
       TableData data = (TableData) render("crm_pipeline_summary");
       assertThat(data.getColumns()).hasSize(3);
       assertThat(data.getRows()).hasSize(3);
-      assertCell(data, 0, "first", "Open (2 deals)");
-      assertCell(data, 0, "second", "300.00");
-      assertCell(data, 0, "third", "40.50");
-      assertCell(data, 1, "first", "Won (0 deals)");
+      assertCell(data, 0, "first", "Open");
+      assertCell(data, 0, "second", "2");
+      assertCell(data, 0, "third", "40.5");
+      assertCell(data, 1, "first", "Won");
       assertThat(data.getDropdownNameList()).containsExactly("pipelineId");
       RenderWidgetInput selected = new RenderWidgetInput().withWidgetMetaData(QContext.getQInstance().getWidget("crm_pipeline_summary"));
       selected.addQueryParam("pipelineId", "2");
       TableData other = (TableData) new CrmHomeRenderer().render(selected).getWidgetData();
       assertThat(other.getRows()).hasSize(1);
-      assertCell(other, 0, "first", "Other (1 deals)");
+      assertCell(other, 0, "first", "Other");
       selected.addQueryParam("pipelineId", "999");
       assertThat(((TableData) new CrmHomeRenderer().render(selected).getWidgetData()).getRows()).hasSize(3);
       assertLinks(data);
@@ -223,7 +271,7 @@ class CrmHomeWidgetsTest extends BaseTest
       assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_goals")).isFalse();
       assertThat(data.getRows()).hasSize(1);
       assertCell(data, 0, "first", TEST_USER_ID + " (50.0%)");
-      assertCell(data, 0, "second", "500.50");
+      assertCell(data, 0, "second", "500.5");
       assertCell(data, 0, "third", "250.25");
       assertLinks(data);
    }
@@ -247,7 +295,7 @@ class CrmHomeWidgetsTest extends BaseTest
       assertThat(data.getRows()).hasSize(2);
       assertCell(data, 0, "first", "Ada");
       assertCell(data, 0, "second", "2");
-      assertCell(data, 0, "third", "251.00");
+      assertCell(data, 0, "third", "251");
       assertLinks(data);
    }
 
@@ -331,7 +379,7 @@ class CrmHomeWidgetsTest extends BaseTest
     *******************************************************************************/
    private void assertStatistic(String name, String expected) throws QException
    {
-      assertThat(new BigDecimal(((StatisticsData) render(name)).getCount().toString())).isEqualByComparingTo(expected);
+      assertThat(new BigDecimal(((StatisticsData) render(name)).getCount().toString().replace(",", ""))).isEqualByComparingTo(expected);
    }
 
 

src/test/java/com/kingsrook/qbits/crm/widgets/CrmSetupStatusTest.java

@@ -0,0 +1,204 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2026.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.kingsrook.qbits.crm.widgets;
+
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import com.kingsrook.qbits.crm.BaseTest;
+import com.kingsrook.qbits.crm.security.CrmPermissions;
+import com.kingsrook.qqq.backend.core.actions.dashboard.RenderWidgetAction;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionEnforcement;
+import com.kingsrook.qqq.backend.core.actions.permissions.PermissionsHelper;
+import com.kingsrook.qqq.backend.core.context.QContext;
+import com.kingsrook.qqq.backend.core.exceptions.QPermissionDeniedException;
+import com.kingsrook.qqq.backend.core.model.actions.widgets.RenderWidgetInput;
+import com.kingsrook.qqq.backend.core.model.dashboard.widgets.TableData;
+import com.kingsrook.qqq.backend.core.model.data.QRecord;
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+
+/*******************************************************************************
+ ** The Setup card: what is missing is called out with its consequence, what is
+ ** in place is marked set up, and the card renders on the home.
+ *******************************************************************************/
+class CrmSetupStatusTest extends BaseTest
+{
+   /*******************************************************************************
+    ** Nothing configured: the business setup the CRM needs are flagged.
+    *******************************************************************************/
+   @Test
+   void emptyInstallNeedsSetup() throws Exception
+   {
+      Map<String, CrmSetupStatus.Item> items = items();
+      assertThat(items).containsOnlyKeys("Default pipeline", "Pipeline stages", "Lifecycle stages", "Base currency");
+      assertThat(items.get("Default pipeline").state()).isEqualTo(CrmSetupStatus.State.TODO);
+      assertThat(items.get("Default pipeline").detail()).contains("Convert lead fails");
+      assertThat(items.get("Pipeline stages").state()).isEqualTo(CrmSetupStatus.State.TODO);
+      assertThat(items.get("Lifecycle stages").detail()).contains("Lead and Opportunity");
+      assertThat(items.get("Base currency").state()).isEqualTo(CrmSetupStatus.State.TODO);
+   }
+
+
+
+   /*******************************************************************************
+    ** A default pipeline without a closed-won or closed-lost stage still needs setup.
+    *******************************************************************************/
+   @Test
+   void pipelineNeedsClosedStages() throws Exception
+   {
+      CrmHomeWidgetsTest.seed("crm_pipeline", new QRecord().withValue("id", 1).withValue("name", "Sales").withValue("isDefault", true));
+      assertThat(items().get("Default pipeline").state()).isEqualTo(CrmSetupStatus.State.OK);
+      assertThat(items().get("Pipeline stages").detail()).contains("no stages");
+
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 1).withValue("pipelineId", 1).withValue("name", "Open").withValue("sortOrder", 1));
+      assertThat(items().get("Pipeline stages").state()).isEqualTo(CrmSetupStatus.State.TODO);
+      assertThat(items().get("Pipeline stages").detail()).contains("no Closed Won");
+
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 2).withValue("pipelineId", 1).withValue("name", "Won").withValue("sortOrder", 2).withValue("isClosedWon", true));
+      assertThat(items().get("Pipeline stages").detail()).contains("no Closed Lost");
+
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 3).withValue("pipelineId", 1).withValue("name", "Lost").withValue("sortOrder", 3).withValue("isClosedLost", true));
+      assertThat(items().get("Pipeline stages").state()).isEqualTo(CrmSetupStatus.State.OK);
+   }
+
+
+
+   /*******************************************************************************
+    ** Lifecycle stages name exactly what is missing; currency needs a base.
+    *******************************************************************************/
+   @Test
+   void lifecycleAndCurrency() throws Exception
+   {
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 1).withValue("name", "Lead"));
+      assertThat(items().get("Lifecycle stages").detail()).contains("Missing Opportunity").doesNotContain("web leads");
+      assertThat(items().get("Lifecycle stages").nextStep()).contains("\"Opportunity\"");
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 2).withValue("name", "Opportunity"));
+      assertThat(items().get("Lifecycle stages").state()).isEqualTo(CrmSetupStatus.State.OK);
+
+      CrmHomeWidgetsTest.seed("crm_currency", new QRecord().withValue("currencyCode", "EUR").withValue("isBaseCurrency", false));
+      assertThat(items().get("Base currency").state()).isEqualTo(CrmSetupStatus.State.TODO);
+      CrmHomeWidgetsTest.seed("crm_currency", new QRecord().withValue("currencyCode", "USD").withValue("isBaseCurrency", true));
+      assertThat(items().get("Base currency").detail()).startsWith("USD");
+   }
+
+
+
+   /*******************************************************************************
+    ** The card renders on the home with one linked row per item.
+    *******************************************************************************/
+   @Test
+   void rendersOnTheHome() throws Exception
+   {
+      assertThat(CrmHomeWidgets.HOME).contains("crm_setup");
+      TableData data = (TableData) CrmHomeWidgetsTest.render("crm_setup");
+      assertThat(data.getRows()).hasSize(4);
+      CrmHomeWidgetsTest.assertCell(data, 0, "first", "Default pipeline");
+      assertThat(data.getRows().get(0).get("second").toString()).contains("Needs setup");
+      
+   }
+
+
+
+   /*******************************************************************************
+    ** The checklist is business setup only: no email-provider row.
+    *******************************************************************************/
+   @Test
+   void noEmailProviderRow() throws Exception
+   {
+      assertThat(items().keySet()).noneMatch(label -> label.toLowerCase().contains("email"));
+      TableData data = (TableData) CrmHomeWidgetsTest.render("crm_setup");
+      assertThat(data.getRows().toString()).doesNotContain("email qbit").doesNotContain("Email delivery");
+   }
+
+
+
+   /*******************************************************************************
+    ** Settings holders get the card while setup is incomplete, and not once complete.
+    *******************************************************************************/
+   @Test
+   void settingsHolderSeesCardOnlyWhileIncomplete() throws Exception
+   {
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isTrue();
+
+      completeSetup();
+      assertThat(CrmSetupStatus.isIncomplete()).isFalse();
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isFalse();
+      assertThatThrownBy(() -> renderEnforced()).isInstanceOf(QPermissionDeniedException.class);
+   }
+
+
+
+   /*******************************************************************************
+    ** A CRM user without the settings permission never gets the card, incomplete or not.
+    *******************************************************************************/
+   @Test
+   void nonSettingsUserNeverSeesCard() throws Exception
+   {
+      QContext.getQSession().setPermissions(Set.of(CrmPermissions.APP_ACCESS, CrmPermissions.READ, CrmPermissions.WRITE));
+      assertThat(CrmSetupStatus.isIncomplete()).isTrue();
+      assertThat(PermissionsHelper.hasWidgetPermission(new RenderWidgetInput(), "crm_setup")).isFalse();
+      assertThatThrownBy(() -> renderEnforced()).isInstanceOf(QPermissionDeniedException.class);
+   }
+
+
+
+   /*******************************************************************************
+    ** Render the setup widget the way the UI API does, with permissions enforced.
+    *******************************************************************************/
+   private void renderEnforced() throws Exception
+   {
+      RenderWidgetInput input = new RenderWidgetInput().withWidgetMetaData(QContext.getQInstance().getWidget("crm_setup"));
+      input.setPermissionEnforcement(PermissionEnforcement.ENFORCE);
+      new RenderWidgetAction().execute(input);
+   }
+
+
+
+   /*******************************************************************************
+    ** Seed everything the checklist asks for.
+    *******************************************************************************/
+   private void completeSetup() throws Exception
+   {
+      CrmHomeWidgetsTest.seed("crm_pipeline", new QRecord().withValue("id", 1).withValue("name", "Sales").withValue("isDefault", true));
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 2).withValue("pipelineId", 1).withValue("name", "Won").withValue("sortOrder", 2).withValue("isClosedWon", true));
+      CrmHomeWidgetsTest.seed("crm_pipeline_stage", new QRecord().withValue("id", 3).withValue("pipelineId", 1).withValue("name", "Lost").withValue("sortOrder", 3).withValue("isClosedLost", true));
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 1).withValue("name", "Lead"));
+      CrmHomeWidgetsTest.seed("crm_lifecycle_stage", new QRecord().withValue("id", 2).withValue("name", "Opportunity"));
+      CrmHomeWidgetsTest.seed("crm_currency", new QRecord().withValue("currencyCode", "USD").withValue("isBaseCurrency", true));
+   }
+
+
+
+   /*******************************************************************************
+    **
+    *******************************************************************************/
+   private Map<String, CrmSetupStatus.Item> items() throws Exception
+   {
+      List<CrmSetupStatus.Item> items = CrmSetupStatus.load();
+      return (items.stream().collect(Collectors.toMap(CrmSetupStatus.Item::label, item -> item, (a, b) -> a, java.util.LinkedHashMap::new)));
+   }
+
+}