qbit-marketing/docs/DESIGN.md

# QBit Marketing: design

The design of qbit-marketing 0.1.0 as implemented. Operating details are in [OPERATIONS.md](OPERATIONS.md); the starter products and their sources are in [STARTER-DATA.md](STARTER-DATA.md).

## Goals

Automate the repeatable work of marketing our software, inside the host QQQ application:
- research positioning from recorded evidence
- plan campaigns
- prepare content
- coordinate approved execution
- measure outcomes
- recommend improvements

The work is truthful and auditable: facts come from sources with dates, people approve exactly what goes out, and results never claim more than was measured.

## Existing patterns reused

| From | Reused for |
|---|---|
| **qbit-assistant** (0.1.0-RC.2) | The model-provider SPI: `AssistantModelProvider`, `ModelRequest` / `ModelResponse` / `ModelPart`, `StreamHandle`, `ModelProviderException` with its retryable kinds, and `ModelUsage`. Since RC.12 it lives in `com.kingsrook.qbits.assistant.spi` (`qbit-assistant-provider-api`), together with `ModelPricing` for cost; hosts register a provider such as `qbit-assistant-provider-anthropic` or `qbit-assistant-provider-openai`. There is no second provider abstraction. |
| **QQQ AI tool kernel** (qqq#1078, core) | The tool contract: `AbstractAiTool` / `AiToolKind` (READ, WRITE_PROPOSAL), `AiToolOutcome`, the `qqq_data` untrusted-data envelope (`AiDataEnvelope`), secret redaction (`AiRedactor`), strict input keys, and running as the user's session. The RC.6 baseline includes `AiToolRegistry` (QRun-IO/qqq#1096); Marketing contributes its read tools there and runs its own agent tools with the same contract. |
| **QQQ core permission enforcement** (qqq#1061) | Agent tools read with `PermissionEnforcement.ENFORCE`. Service entry points check their step's permission, then run as trusted internal work in an authorized scope, as QQQ does for calls nested in a core action. Record security locks always apply. |
| **qbit-assistant / sql-workbench metadata builders** | Explicit builder-produced tables (not annotation scanning), snake_case `marketing_*` names, QQQ standard permission suffixes, `DenyBehavior.HIDDEN`, read-only system tables, record locks, reference DDL in `docs/ddl`, `tableMetaDataCustomizer` and `inferBackendNames`. |
| **Website-Backend admin conventions** | Processes are table and record actions, never nav items, with plain labels. Record actions use `StreamedETLWithFrontendProcess` with standard summary lines. App homes are real-data dashboards built from ≤3-column full-width tables. Links use the Next route grammar (`AiLinkBuilder`). |
| **qbit-crm** | The CRM itself, via a gateway: consent records, `doNotEmail` / unsubscribe, list membership, form submissions with UTM, and "Note" activities. |
| **QQQ messaging** | `SendMessageAction` and the host's `QMessagingProviderMetaData` for email. |
| **QQQ ESB / Quick Search** | Every write goes through core table actions, so record-change listeners (ESB publications) and Quick Search indexing apply. Hosts list `MAIN_TABLE_NAMES` in their ESB and Quick Search config (Voyage does this for Quick Search). |

## Data model (19 tables)

**Main tables** (in the nav):

| Table | Holds |
|---|---|
| `marketing_product` | The product brief: maturity, tagline, summary, value propositions, license, platforms, latest release, adoption path, official URLs and last verification date. |
| `marketing_campaign` | Goal, status, audience, objective, problem, messaging, channel plan, call to action, destination, UTM campaign, schedule, owner, success criteria and the lead-qualification rule. |
| `marketing_content` | The proposed publication: title, body, destination, call to action, recipient scope, schedule and channel. Managed fields: status, revision number, content hash, author type and agent run. |
| `marketing_execution` | A durable job: approval, revision, channel, transport, schedule, status, idempotency key, attempts, backoff, receipt, lease and test-data flag. |
| `marketing_agent_run` | Task, status, instructions, provider, model, requester, times, model and tool calls, tokens, cost, drafts and findings created, summary, output JSON and error. |

**Settings tables** (in the nav):

| Table | Holds |
|---|---|
| `marketing_channel` | Type, transport, active flag, automation allowed, AI-content policy, rules summary and source, rules verification date, hourly rate, recipients per execution. |
| `marketing_policy` | Kill switches for the agent and execution, provider and model overrides, the daily token budget, the monthly cost budget, and concurrency and tool limits. |

**Sub-tables** (child lists on their parents):

| Table | Parent | Notes |
|---|---|---|
| `marketing_audience` | product | |
| `marketing_evidence_source` | product | With its verification date. |
| `marketing_claim` | product, source | Status, evidence quote, discrepancy note. |
| `marketing_content_revision` | content | Immutable. |
| `marketing_approval` | content | Hash-bound. Status: active, invalidated, revoked or consumed. |
| `marketing_execution_attempt` | execution | |
| `marketing_test_delivery` | execution | What the test transport accepted. |
| `marketing_agent_step` | agent run | Model calls, tool calls and checks. |
| `marketing_finding` | product, campaign, content, agent run | |
| `marketing_metric` | campaign | The measurement plan. |
| `marketing_outcome_event` | campaign | Raw events, deduplicated by (source, external id). |
| `marketing_metric_daily` | campaign | **Daily Results**: the persisted rollup of the events per UTC day, stage, event type and test-data flag. System-written and read-only. |

Most rows carry a denormalized `productId`, so the optional product security lock covers every table. `scripts/generate-model.py` generates the entities, the 21 enum possible-value sources and the DDL from one spec.

## Content, revisions and approval

- **Revisions:** `MarketingContentCustomizer` hashes the approved fields (`ContentHasher`): title, body, destination, call to action, recipient scope, schedule (to the second) and channel. Every insert and every change to one of those fields appends a revision.
- **Edits after approval:** a hash change voids every active approval (recorded with the reason), returns the content to Draft, and blocks its scheduled or paused executions.
- **Managed fields:** people can't set status or the managed fields directly. Status moves only through the actions, which run inside `MarketingInternalWrite`.
- **Approve:** the person must hold `marketing.approve.hasAccess`. The content must be In Review with no open blocker findings, and pass the channel's AI-content rule:
  - *Not allowed* refuses agent-written revisions.
  - *Unknown* refuses them until the rules are recorded.
  - *With disclosure* requires the disclosure text in the body.
  - Optionally, the approver must not be the revision's author.
  - The approval row stores the hash, revision, destination, scope and schedule.
- **Guarded tables:** approvals, executions, attempts, revisions, test deliveries, agent runs and steps, and the daily results are read-only in the UI and API. A guard customizer rejects any write outside Marketing's services, including the generic API and any tool.

## Execution

- **Schedule:** `Schedule` (`marketing.execute.hasAccess`) creates one execution per approval (idempotency key `marketing-execution:<content>:<approval>`). It refuses a channel whose transport isn't registered: a declared channel name is not a connector.
- **Worker:** `Run Due Executions` runs scheduled on the host scheduler, or by hand. It holds one lock per JVM, recovers expired leases first, then runs each due execution.
- **Checks before every send:**
  1. the policy kill switch
  2. the execution is still Scheduled (so paused and cancelled work never runs)
  3. the approval is still Active, with the same hash as the content
  4. the approved schedule has been reached
  5. the channel is active
  6. the transport is registered, usable (Operational or Test only), and serves the channel type
  7. the channel allows automation (except on the test transport)
  8. the channel's AI-content rule
  9. the channel's hourly rate (over it, the send is postponed, not failed)
  10. for CRM recipients: the scope is resolved through the gateway now, each contact's consent and suppression is re-checked, ineligible contacts are excluded and counted, it is blocked when nobody is left, and blocked over the per-execution limit (no bulk outreach)
- **Claim:** the execution moves to Running with a lease, the attempt counter is incremented, and the transport gets the exact approved text and the idempotency key.
- **Outcomes:**
  - *Accepted* or *Duplicate*: Accepted by provider. The approval is consumed, the content is Accepted, and one Delivery-stage `provider_accepted` event is recorded. That is not delivery or engagement.
  - *Rejected*: Failed.
  - *Retryable failure* (certainly not sent): rescheduled with exponential backoff until `maxAttempts`, then Failed.
  - *Ambiguous*: Needs reconciliation, never retried automatically. **Reconcile with Provider** asks the transport (`lookup`). **Mark as Accepted** and **Mark Not Sent and Retry** record a person's decision; a retry reuses the idempotency key, so the transport can drop a repeat.
  - *Lease expired* (the worker died mid-send): Needs reconciliation.
- **Transports:** `MarketingTransport` defines `getStatus` (Not configured / Configured / Operational / Test only), `send`, which never throws for provider outcomes, and `lookup`.
  - `ControlledTestTransport` is complete. It stores each payload per recipient, honors idempotency keys (repeats are counted, not stored), and supports scripted failures for tests and demos.
  - `QqqMessagingEmailTransport` is one message per recipient. It reports Configured but not Operational until the host verifies its provider. Exceptions are Ambiguous, because SMTP and SES can fail after accepting.

## Measurement

`MeasurementReport` (the campaign Results widget and the agent's results tool) works from the campaign's metrics: stage, event type, count mode and instrumentation status.

- **Separation:** Delivery, Awareness, Engagement, Activation, Repeat use and Qualified demand are separate rows.
- **Counts:** each metric shows raw events (summed quantities) and unique actors (distinct `actorKey`). Events without an actor are noted.
- **Missing instrumentation:** a Not instrumented metric shows **Not measured**, never 0. Partial instrumentation is a lower bound. Stages with no metric and events outside the plan are listed as limitations.
- **Test data:** test executions and fixtures are flagged `isTestData` and excluded from the numbers, with a count.
- **Fixed limitations:** provider acceptance is not delivery; visits, stars and downloads are not adoption.
- **Deduplication:** outcome events are deduplicated by the unique key (source, external id) on every insert path: the admin UI, the API and services.
- **Daily rollup:** the report does not load the campaign's events. `marketing_metric_daily` holds, per campaign, UTC day (`dayUtc`), stage, event type and test-data flag: the raw count (sum of quantities), the unique actors of that day and the events without an actor. The unique key is (campaign, day, stage, event type, test data).
  - **Kept in step:** `OutcomeEventRollupCustomizer` recomputes the affected (campaign, day)s after every insert, update and delete of an event, from any path (table, API, CRM import, importer, the execution worker). An update recomputes the old and the new day. `MeasurementRollupService` re-reads that day's raw events and upserts by the unique key, rewriting a row only when its numbers differ, and deletes rows that no longer have events. It is idempotent.
  - **Rebuild Results** (campaign record action, `marketing.prepare`, the same permission as Update Results from CRM) rebuilds every day of the selected campaigns, so a damaged rollup, or events written outside Marketing, can be repaired.
  - **Unique actors are not summed from days** (the same actor on two days is one actor). The report counts them over the whole campaign with a backend `COUNT_DISTINCT` of `actorKey` grouped by stage and event type; raw counts are backend `SUM`s over the rollup. Nothing is aggregated in memory.
  - **Events always have a time and a test flag:** an insert defaults `occurredAt` to now and `isTestData` to false; a blank `actorKey` is stored as null; an event cannot lose its time.
  - **Written only by Marketing:** the table is in `SYSTEM_WRITTEN_TABLE_NAMES` (guarded, no insert, edit or delete in the UI or API), carries `productId` for the product record lock and shows as the **Daily Results** child list on the campaign.
- **Importers:** `MarketingOutcomeImporter` (`getName()`, `fetch(campaign, since)`) is the SPI for an analytics source, registered with `MarketingQBitConfig.withOutcomeImporter(...)`. **Import Outcomes** (campaign record action) runs every importer and stores each `ImportedOutcome` through the normal insert path with the importer's name as `source`, so repeats are dropped; `since` is the newest `occurredAt` already recorded for that importer and campaign. A failing importer is named in the result and does not stop the others. The qbit ships no concrete network importer. The Configuration Status widget lists the registered importers.

## CRM integration

`MarketingCrmGateway` is the whole contract:
- `resolveRecipients(scope)`: addresses only for eligible contacts, used only at send time
- `checkEmailEligibility`
- `listFormSubmissions(utmCampaign)`: ids and times only
- `recordActivity`

`QbitCrmGateway` implements it over qbit-crm 0.2.0's `crm_*` tables (`crm_contact`, `crm_consent_record`, ...) by table name, through the standard actions, so there is no compile dependency on the CRM. It moves to qbit-crm's public `com.kingsrook.qbits.crm.api.CrmMarketingApi` once that is released:
- **Email consent:** the most recent Email consent record decides (Granted and not expired). No record means no consent.
- **Suppression:** `doNotEmail`, an unsubscribe date, or a list membership that isn't Subscribed.

**Update Results from CRM** imports a campaign's attributed form submissions as Engagement events, deduplicated by submission. It then applies the campaign's explicit rule: at least N attributed submissions, and email consent if required. Each newly qualified contact is logged as a CRM "Note" activity and recorded as one Qualified-demand event. Without the rule, nobody is a lead.

## The agent

`MarketingAgentService.run(task, campaign, content, instructions)` is a bounded tool-use loop:

1. **Preflight**, which fails the run with a plain reason: the policy kill switch, provider and model resolved (policy, then config, then the single registered provider), the daily token and monthly cost budgets, and the concurrency permit.
2. **Deterministic readiness checks** (`ReadinessChecker`, also available without the agent as **Check Readiness**), recorded as a CHECK step:
   - missing or stale evidence
   - unverified, unsourced or disputed claims
   - missing audience
   - prelaunch maturity, and goals that don't fit it
   - missing call to action or success criteria
   - measurement gaps
   - unverified channel rules
3. **The loop:**
   - **Inputs:** a fixed system prompt (truth rules, untrusted data, no personal data, no authority to publish) and the task message (ids and the person's instructions only).
   - **Each call:** one model call, then each tool call through `MarketingToolRunner`, which enforces strict keys, the user's session with `ENFORCE`, redaction, a cap of 8000 characters per string, the envelope, and errors as outcomes.
   - **Bounds:** model calls, tool calls, wall-clock time, and model calls per minute.
   - **Cancel:** the run re-reads its status before each model call, so **Cancel Run** stops it.
   - **Retries:** retryable provider errors are retried twice with backoff.
4. **Record:** every step (model calls with tokens and stop reason, tool calls with the input, the outcome and the enveloped result as the model saw it), the usage, the cost (when the model has a price), the drafts and findings created, the redacted final summary, and the plan.

**Tools** (`MarketingTools`). The kind of each tool:
- **READ** (also contributed to the AI tool kernel):
  - `marketing_get_campaign_brief`
  - `marketing_list_product_claims`
  - `marketing_list_campaign_content`
  - `marketing_get_campaign_results` (counts and anonymous actor counts only)
  - `marketing_list_channels`
  - `marketing_list_findings`
- **WRITE_PROPOSAL** (agent only):
  - `marketing_save_draft`: always a Draft by the agent. It refuses channels that forbid AI content, cited claims must belong to the product, and non-released claims raise a BLOCKER finding.
  - `marketing_record_finding`
  - `marketing_submit_plan`

Each task gets only the tools it needs. No tool can approve, schedule, execute or touch the guarded tables. The write-proposal tools need the requester's `marketing.write`, and `marketing_save_draft` revises only content that is still a Draft.

**Review safeguards:**
- **The content edit path:** ids normalized, the old record re-read, never fail open. Execution also re-hashes the fields it is about to send.
- **Approve is pinned:** a record whose content hash changed between the Review screen and execute is skipped.
- **The policy fails closed.**
- **Global limits and budgets** are counted as the system user, across all products.
- **Worker isolation:** one failing execution is blocked without stopping the others.
- **Open blocker findings** can only be closed or downgraded with approval authority.

**Data sent to the provider:** the tool definitions, the fixed prompt, the task text and enveloped tool results. Never CRM addresses, names or contact details: the results tool aggregates, and recipients are resolved only at send time.

## Configuration status

The dashboard's Configuration Status widget (`MarketingRuntime.describeIntegrations`) lists every model provider, transport and the CRM gateway with its honest state:
- *Not configured*
- *Registered (not selected)*
- *Configured (not verified by a live call)*
- *Configured, not verified (executions blocked)*
- *Operational*
- *Test only*
- *Available*

No live call is made to verify a provider or transport.

## Owner decisions (2026-10-12): all recommendations accepted

The owner accepted every recommendation on 2026-10-12. The concrete defaults, recorded 2026-10-13:

**Providers**

| Integration | Default | Why |
|---|---|---|
| Model provider | Claude through `qbit-assistant-provider-anthropic`, model `claude-sonnet-5-5`, set by the host (`ANTHROPIC_API_KEY`, `MARKETING_MODEL`) | The existing provider SPI and pricing table; no second abstraction. |
| OpenAI-compatible provider | Not configured | Optional; register it only for a specific need (for example a local Ollama for experiments). With two providers the host must name one. |
| Email transport | QQQ messaging over Amazon SES, from a verified `qrun.io` domain (SPF, DKIM, DMARC), from-address `news@qrun.io`, replies to `hello@qrun.io` | SES is a low-cost, reliable sender and QQQ messaging supports it directly. Reports *Configured, not verified* until one end-to-end test send, then the host sets `withVerifiedOperational(true)`. |
| Social and community posting | No transports. Posted by hand | No connector exists, and each community's rules must be checked before any automation. |
| Measurement | Outcome events from the CRM import, by hand and from host-registered importers (SPI only); a persisted daily rollup; no third-party analytics provider | Matches the honest-measurement rules: not instrumented shows *Not measured*. |
| CRM gateway | `QbitCrmGateway` (qbit-crm) | What Voyage's Marketing wiring uses. |

**AI-content channel policy**

- The agent drafts and a person approves every publication. The agent never publishes.
- **Owned channels:** email to the opted-in CRM list and the project blog are *Allowed with disclosure*, with the default `aiDisclosureText` ("Prepared with AI assistance.").
- **GitHub release notes:** *Allowed*, without disclosure. A maintainer checks every line against the release's merged changes before publishing.
- **Third-party community channels** (forums, Reddit, Hacker News, social networks): *Not allowed* for agent-written text. A new community channel starts *Not allowed*, or *Unknown* until its current rules are read and recorded with a verification date. Never loosen one without its rules on file.
- **Test sink:** *Allowed*.

**Policy row and approval**

- `default` policy: agent and execution on, 1,000,000 tokens a day, a **USD 25 monthly cost limit** (`monthlyCostLimitMicros` 25,000,000), 2 concurrent runs, 24 tool calls per run.
- `requireDifferentApprover` stays `false`: the team is one person. Turn it on when a second approver exists.

The starter data (`marketing-starter-data.json`) carries these channel policies, verification dates and the cost limit.