@learncard/network-brain-service 4.1.2 → 5.0.0

package/src/accesslayer/campaign/README.md

@@ -1,8 +1,7 @@
 # Campaigns: setup, audiences and engagement (LC-2265)
 
-This slice stores campaign definitions, server-selected audiences and shared engagement
-state. It does not deliver notifications or render messages. LC-2266 owns dispatch and
-`sendTestToMe`; LC-2267 owns app integration. It does not require the in-app messages V2
+This service stores campaign definitions, server-selected audiences, shared engagement
+state and paced notification delivery. LC-2267 owns app rendering and tap routing. It does not require the in-app messages V2
 branches: `message` uses the shared `InAppMessage` schema available in this checkout.
 
 ## Administration and lifecycle
@@ -34,7 +33,7 @@ the campaign and its relationships.
 Use a new ID for a new campaign; deleting/reusing an ID cannot clear clients' local seen state.
 
 `channels` must contain `inApp`, `notify`, or both without duplicates. `notify` requires
-`notification: { title, body }`, but does not send anything in this slice. Dates are ISO
+`notification: { title, body }`, but sends only after an explicit test or dispatch. Dates are ISO
 timestamps normalized to UTC; `startsAt` is inclusive and `endsAt` is exclusive. If both
 exist, the end must follow the start. Partial updates preserve omitted fields; `null`
 clears optional notification/start/end fields. Updates replace `message` as a whole.
@@ -144,7 +143,7 @@ duplicate state edges and lost increments under concurrent devices. Repeated req
 are separate events, not transport-idempotent retries.
 
 Stats count distinct profiles, not impressions; `enrolled` counts memberships originally
-created by self-enrollment. `notified` is reserved for LC-2266 and is not client-writable.
+created by self-enrollment. `notified` counts durable inbox acknowledgements and is not client-writable.
 All user/discovery calls share a 60-call/profile/minute rate limit; admin operations do not.
 
 The network plugin exposes `learnCard.invoke.getMyCampaigns()`,
@@ -166,9 +165,279 @@ does not read the developer's database. Docker is required. The suite covers all
 types, permissions, injection rejection, minor rules, paging, lifecycle, enrollment and
 concurrent shared state. Schema tests live in `@learncard/types`; SDK forwarding tests
 live in `@learncard/network-plugin`. Hosted CI runs the Neo4j suite separately from the
-service's default unit suite. No app UI, notification delivery or device QA is claimed.
+service's default unit suite. No app UI or device QA is claimed. Delivery coverage is described below.
 
 The hosted Linux verification workflow also runs `test/verification/campaigns.ts` via
 `lc verify script` after the full catalog: real signed SDK calls prove non-admin denial
 and user isolation over HTTP. The default stack grants no admin access, so positive
 administration and graph mutations are covered by the dedicated Neo4j suite instead.
+
+## Notification delivery (LC-2266)
+
+```ts
+// Allowlisted administrator, with campaigns:admin scope.
+await learnCard.invoke.campaignsSendTestToMe('transcript-pilot-v1');
+await learnCard.invoke.campaignsSetStatus('transcript-pilot-v1', 'live');
+const { dispatchId } = await learnCard.invoke.campaignsDispatch('transcript-pilot-v1');
+```
+
+`sendTestToMe` always targets the authenticated administrator and tests the selected channels.
+It ignores audience, status and dates. `notify` uses the saved notification copy and existing
+notification queue; `inApp` stores a private snapshot on a `CAMPAIGN_TEST` relationship.
+In-app JSON is optional for notification-only campaigns, and notification copy is optional
+for in-app-only campaigns. At least one channel and its corresponding content are required.
+Each explicit test gets a fresh test ID; notification queue retries preserve it.
+
+The existing `getMyCampaigns` endpoint includes pending private snapshots only for their
+requesting administrator, with a `testId`. Reading does not consume a test. After the real
+renderer presents it, `recordEvent` with `{ campaignId, event: 'shown', testId } removes that
+snapshot without writing engagement state. A stale acknowledgement cannot remove a newer
+snapshot. The latest test replaces the pending one for that administrator/campaign; deleting
+the campaign deletes its pending tests. LearnCard App fetches on entry/return outside the
+composer, keeps tests account/network-scoped, and does not send their events to analytics.
+Test sends neither enroll the caller nor increment campaign stats.
+`dispatch`requires a live, in-window campaign with the`notify` channel. The queue job
+contains campaign ID, creation timestamp, dispatch ID and an optional profile-ID cursor.
+The creation timestamp prevents old jobs from applying to a deleted/recreated campaign.
+
+Audience pages are ordered by profile ID, reapply the existing age policy and default to
+1000 recipients. Full pages schedule the next cursor after 60 seconds. Thus 2500 recipients
+use three waves; an exact multiple can schedule an empty final page. The defaults are
+configurable through `CAMPAIGN_DISPATCH_PAGE_SIZE` and `CAMPAIGN_DISPATCH_DELAY_SECONDS`.
+A re-dispatch starts at the beginning, including newly added members with earlier IDs,
+and skips recipients with `notifiedAt`.
+
+Announcements include `metadata.campaignHasInApp`, true only for an enabled in-app
+channel on an ordinary delivery. Notification-only campaigns, disabled messages,
+and admin notification self-tests fall back to the inbox. Clients require an explicit
+true flag before routing to `/m/:id` or showing the inbox card's View action. Older
+stored announcements without the flag also stay in the inbox.
+
+The worker sends ANNOUNCEMENT via the existing notification queue. Each recipient is
+checked again before enqueue and before webhook delivery. Paused, archived, expired,
+deleted, no-longer-notify and age-ineligible campaigns/recipients stop future delivery;
+a send already in flight at a pause can still complete. Resume with an explicit dispatch.
+The local fallback awaits all waves and their delays and loses unfinished work on process
+exit; use a small page size/delay during development and SQS for production.
+
+### Retry and statistics boundary
+
+Enqueue and Neo4j are separate systems: duplicate queue messages are expected after a
+lost enqueue response, concurrent dispatches, worker retries or acknowledgement failure.
+There is deliberately no pre-send `notifiedAt` marker that could silently lose deliveries.
+lca-api atomically inserts one inbox record using its Mongo `_id` uniqueness constraint,
+keyed by sender, recipient, campaign ID and creation timestamp (plus test ID for tests).
+Only the inserting request attempts push. Retries preserve existing read/archive state
+and copy. This is a narrowly approved extension of the ticket's original enum-only scope;
+it leaves the existing FCM delivery path intact.
+
+After lca-api acknowledges durable storage, brain records `notifiedAt` under the same
+profile lock as engagement writes. Queue acceptance alone is not counted. If that graph
+write fails, the notification retries; lca-api returns success for the existing record
+without another push attempt. Stats measure acknowledged inbox storage, **not** device
+receipt. FCM remains best effort: a crash between inbox insertion and push, or a push
+failure, can leave an inbox card without push. There is no exactly-once device guarantee.
+Receiver deduplication lasts while the inbox record exists; hard-deleting it before an
+unacknowledged retry can permit reinsertion. Production pilot QA must include this existing
+notification retention limitation.
+
+### Custom webhook compatibility
+
+Audience selection does not exclude profiles with a custom `notificationsWebhook`.
+Their endpoint takes precedence over the default lca-api webhook in hosted environments;
+do not assume every audience member uses the LearnCard inbox. An arbitrary HTTP 2xx
+response is not proof of durable storage for ANNOUNCEMENT notifications. Compatible
+receivers must persist the notification before returning JSON `true`, or a boolean
+`sent`, `success`, or `ok` flag set to `true` (also accepted under `data` or `result.data`).
+An explicit `false` is a negative acknowledgement. Empty responses (including 204),
+plain text, and unrecognized JSON such as `{"status":"ok"}` remain uncertain and retry;
+they do not advance `notifiedAt`.
+
+Custom receivers must deduplicate retries by sender DID, recipient DID, `campaignId`,
+and `campaignCreatedAt`, adding `campaignTestId` for test sends. Return the same positive
+acknowledgement for an already stored notification without repeating downstream effects.
+Only lca-api's implementation is covered by the inbox/push deduplication guarantee above.
+For a custom receiver, `notified` means its durable-storage acknowledgement was received,
+not that a LearnCard inbox card or device push exists. Before including custom-webhook
+profiles in a pilot, confirm this contract with the receiver owner using disposable test
+profiles; exclude incompatible receivers from the pilot audience until adapted. Production
+audiences and third-party implementations have not been inventoried by this change.
+
+### Worker network access
+
+The shared notifications worker uses `PrivateSubnetA` because campaign eligibility and
+acknowledgement need private graph/cache access. This applies to all notification types.
+`serverless.yml` declares the outbound path as `PrivateSubnetA` → `PrivateRouteTable`
+→ `PrivateRoute` (`0.0.0.0/0`) → `NatGateway` in `PublicSubnetA` → `PublicRouteTable`
+→ `PublicRoute` → `InternetGateway` attached to the VPC. The NAT has an Elastic IP;
+`ServerlessSecurityGroup` uses AWS's default outbound allowance. A configuration
+regression test protects this complete path.
+
+Private connectivity does not authorize profile-selected HTTP destinations. All hosted
+notification delivery (ordinary notifications, campaigns, explicit queue overrides and
+the default configured webhook) goes through `notification-webhook-fetch.helpers.ts`.
+It accepts HTTP(S) URLs without credentials, rejects nonpublic IP literals, and checks
+every DNS answer before pinning the HTTP connection to a validated literal IP. HTTP Host,
+TLS SNI and certificate verification retain the original hostname. Mixed public/private
+answers and resolution errors fail closed; every attempt resolves again. The transport
+never resolves the hostname a second time, preventing DNS rebinding.
+The IPv6 policy permits global unicast only, excluding special-purpose, documentation
+and transition ranges. Redirects are rejected, so neither the JWT nor notification body
+can be forwarded to a redirect target. The explicit HTTP(S) transport avoids runtime fetch dispatcher differences
+on Node and Bun, and caps acknowledgement bodies at 64 KiB. A blocked delivery does not advance `notifiedAt`; queue failures retain
+the existing retry/dead-letter behavior.
+
+Hosted custom webhooks must resolve exclusively to public addresses and respond directly
+at the configured URL. Private default endpoints are also rejected; no profile or queued
+payload can opt out. Only the trusted `IS_OFFLINE` runtime flag permits local development
+destinations, with redirects still disabled. `NODE_ENV=test` is not an exemption.
+
+This establishes the source configuration, not the deployed AWS state. Before rollout,
+verify the target stack's subnet/route associations, available NAT and internet gateway,
+and effective security-group/network-ACL egress, then exercise an operator-controlled
+external webhook from that worker using a disposable profile. Check both an ordinary
+notification and a campaign acknowledgement. Local and hosted CI do not prove live NAT
+connectivity; no deployment or live delivery is performed by these tests.
+
+### Deployment and proof
+
+Deploy lca-api (enum plus campaign deduplication), then brain, then the separate app
+integration. Pilot with draft → audience preview → test-to-me → live → dispatch. This
+implementation does not authorize deployment or any real audience send. Preserve LC-2265's
+age policy and obtain its documented product/legal sign-off before a pilot.
+
+Focused tests cover three-wave paging, delays, eligibility, stable retry identities,
+receiver deduplication and acknowledgement failures. The Neo4j campaign suite covers
+admin denial, caller-only tests, concurrent state acknowledgements and stats. The lca-api
+notification integration suite covers concurrent receiver storage and push suppression.
+Hosted `lc verify` additionally exercises SDK authorization; it does not provision FCM
+or prove iOS/Android device receipt. Those require separately authorized device QA.
+
+## Reviewed dispatch from the composer
+
+`campaigns.previewDispatch` is an admin-only, read-only query taking `{ campaignId }`.
+The SDK exposes it as `learnCard.invoke.campaignsPreviewDispatch(campaignId)`.
+It returns `audienceCount`, `alreadyNotifiedCount`, `recipientCount`, `notificationRecipientCount`, `emailRecipientCount`, `previewToken`,
+and an optional `blockedReason` (`not_live`, `notify_disabled`, `not_started`, `ended`,
+`no_recipients`). The total counts distinct profiles across the selected delivery channels.
+Inbox counts follow the campaign age policy and exclude push opt-outs and profiles with `notifiedAt`.
+Email counts require adults, announcements enabled, exactly one valid verified primary email,
+and neither `emailClaimedAt` nor `emailedAt`. Neither count guarantees receipt.
+
+After reviewing the count, pass `{ expectedPreviewToken: preview.previewToken }` as
+the second argument to `learnCard.invoke.campaignsDispatch`. The route accepts that
+optional field alongside `campaignId`. Legacy dispatch callers can omit it; the composer
+always supplies it. Under the campaign node lock, the server recomputes a digest over
+the definition, mutation revision, sorted eligible profile IDs and email destinations, rejects stale previews
+with `CONFLICT`, and advances the revision to consume the confirmation once. This catches
+same-count recipient changes as well as ordinary audience edits. No recipients or invalid
+status/schedule/channel is rejected before enqueue. Preview does not mark anyone notified.
+
+The count query collects eligible profile IDs internally to fingerprint the recipient set;
+those IDs are not returned by the API. Confirmed sends support at most 10,000 eligible
+recipients. Cypher limits the collection to 10,001 IDs (one overflow sentinel) before
+transferring them to Node. Larger previews and confirmations return `BAD_REQUEST` and
+require reducing the audience; the server never authorizes a truncated recipient set.
+The confirmation lock is released before queue/network work. Later waves still use current
+eligibility and audience semantics, so the reviewed count is a snapshot rather than a frozen
+send list. Existing queue retries and receiver deduplication remain unchanged. If enqueue
+fails or the HTTP response is lost, review again before retrying; never reuse the old token.
+
+### Concurrent authoring
+
+Content editors should pass the loaded campaign's `updatedAt` as `expectedUpdatedAt`
+to `campaignsUpdate`, and leave lifecycle status changes to `campaignsSetStatus`.
+The server compares the token after acquiring the campaign write lock and rejects
+stale saves with `CONFLICT`. Reload the latest definition before reconciling edits;
+never automatically retry a full stale form against a fresh token. Successful
+writes advance the timestamp monotonically, including same-millisecond writes.
+Legacy SDK callers may omit the optional token; those callers retain existing
+last-write behavior and do not receive optimistic concurrency protection.
+
+## Announcement email (LC-2268)
+
+Campaigns can include `email` alongside `inApp` and `notify`. Supply `email.subject`,
+`title`, `body`, and `ctaLabel`; `heroImageUrl` is optional and must be HTTPS. Body
+copy is plain text, escaped by React. Keep announcement copy free of private learner
+or credential data. Create records capture the request's resolved tenant; queued
+waves use that stored tenant for branding and `/m/<id>?utm_source=email&utm_campaign=<id>`.
+Legacy records without a tenant use the configured default tenant.
+The CTA origin comes from the deployment-owned `CAMPAIGN_APP_ORIGINS` JSON map.
+Stage configs map LearnCard staging to `staging.learncard.ai`, VetPass staging to
+`staging.vetpass.app`, and ScoutPass staging to `staging.pass.scout.org`. Production
+configs supply their corresponding production origins. Queued sends do not use
+request headers to choose an app origin. Custom deployments must configure a map;
+missing, malformed, credential-bearing or non-origin URLs fail preparation before
+the durable email claim. HTTP is allowed only for loopback development origins.
+
+In bundle-enabled Lambda deployments, set `POSTMARK_BROADCAST_STREAM` and
+`CAMPAIGN_UNSUBSCRIBE_SECRET` in **LearnCard Runtime** →
+`/learncard/brain-service/runtime` (`staging` / `prod`), alongside `POSTMARK_API_KEY`.
+Infisical syncs the existing AWS bundle selected by `RUNTIME_SECRETS_ID`; no new
+GitHub per-key mapping is needed. The API, queue worker and unsubscribe handler
+load the bundle before application imports. Recycle/redeploy Brain after sync;
+keep the signing secret stable so previously sent unsubscribe links remain valid.
+Local/Docker uses private `.env` values from the separate LearnCard project.
+See [runtime configuration](../../../../../../environment-variables.md#campaign-email-runtime-settings-brain-service).
+
+Email dispatch requires `POSTMARK_API_KEY`, `DOMAIN_NAME` (the public Brain host),
+`POSTMARK_BROADCAST_STREAM` (default `broadcast`) and `CAMPAIGN_UNSUBSCRIBE_SECRET`
+(a dedicated random secret of at least 32 bytes). The adapter checks the actual
+Postmark stream type is `Broadcasts`; transactional streams are rejected. Provisioning
+these values, enabling a stream, deployment and live sends are separate operator
+steps. No production configuration is included here. `CAMPAIGN_EMAIL_PAGE_SIZE`
+defaults to 500 (1–1000); email and notification jobs keep independent cursors and
+use `CAMPAIGN_DISPATCH_DELAY_SECONDS` between waves.
+
+Email requires exactly one valid primary verified ContactMethod email, a known adult
+profile under the existing campaign adult policy, and no announcement email opt-out.
+Email waves filter adult eligibility and opt-outs before pagination, then recheck both
+under the profile lock before reserving a send. Audience management still lists opted-out members.
+Unknown ages, children, managed non-service profiles and minors fail closed even if
+`excludeMinors` is false. Parent age-policy sign-off is still outstanding: this does
+not authorize marketing to minors. Self-tests bypass audience/status only; they retain
+email eligibility and preferences and do not change production statistics.
+
+A profile lock serializes durable `emailClaimedAt` reservations. A claim commits before
+provider I/O; accepted sends set `emailedAt` and contribute to `getStats().emailed`.
+Retries, concurrent workers and redispatch cannot resend a reserved recipient. This
+is **at-most-once attempt**, not guaranteed delivery: a crash before sending or lost
+provider acknowledgement leaves a reservation with no `emailedAt`. There is no automatic
+lease expiry/replay; an operator must investigate delivery with the provider before any
+future recovery design permits another send. Never clear claims blindly. Provider
+acceptance is not proof of inbox delivery. Archive/pause, generation, membership,
+age, contact and opt-out state are checked at the reservation boundary.
+
+Browser unsubscribe links use the sending Brain service's anonymous
+`/campaigns/unsubscribe/browser?token=...` confirmation page, including ScoutPass.
+GET renders a form; POST applies the opt-out and renders confirmation. This page
+uses no external assets or analytics, sends no-store/no-referrer/CSP headers, and
+supports English, Spanish, French and Arabic using the browser language.
+The `List-Unsubscribe` header uses the Brain HTTPS
+`/campaigns/unsubscribe?token=...` endpoint: it accepts the actual RFC 8058
+`application/x-www-form-urlencoded` POST `List-Unsubscribe=One-Click`, without login,
+cookies, redirects or JavaScript. GET does not mutate. Both POST paths verify the same
+purpose-separated HMAC token, then idempotently set the profile's email opt-out.
+Version 2 tokens bind to a unique, durable `campaignUnsubscribeId` allocated under
+the recipient lock before sending. Renaming a profile preserves its links; reusing
+or deleting a profile name never transfers those links to another account. Legacy
+name-based tokens are rejected because their original recipient cannot be resolved
+safely after a rename. Generate a new test email to replace an old test link.
+Links remain valid after campaign archive/deletion; rotating the secret invalidates
+old links. Tokens are bearer authority for opt-out only, not authentication. Do not
+log token URLs or capture them in analytics; ingress/proxy access-log redaction for
+this endpoint must be checked at deployment. The public endpoint returns no profile data.
+
+Authenticated `getAnnouncementPreferences` and `updateAnnouncementPreferences` return
+and patch `announcementEmailOptOut` / `announcementPushOptOut`. SDK methods use these
+same names, plus anonymous `unsubscribeFromAnnouncements(token)`. Preference fields
+are private graph properties, omitted from public profile projections. Push opt-out
+suppresses both campaign push and inbox at enqueue/delivery checks; in-app selection
+is unaffected. Partial patches leave the other choice unchanged.
+
+Before rollout, use mocked adapter/HTTP tests and the campaign Neo4j suite. Separately
+verify real broadcast receipt and headers, configured public POST ingress, and cold/warm
+`/m/` universal-link handoff on web, iOS and Android in an authorized environment.
+The composer still needs its email controls, counts/wiring and CSV result follow-up.
+
+Audience preview/add responses retain `count` for eligible matches and include `added` (new memberships, zero for preview) and `notFound` (unresolved input DIDs). Age-excluded profiles are not missing. Addition counts are computed under the campaign lock, so retries and aliases cannot inflate them.

package/src/accesslayer/campaign/audience.ts

@@ -1,8 +1,9 @@
 import { TRPCError } from '@trpc/server';
-import { int } from 'neo4j-driver';
+import { int, type ManagedTransaction } from 'neo4j-driver';
 import {
     CampaignAudienceSourceValidator,
     type CampaignAudienceSource,
+    type CampaignAudienceResult,
     type PaginatedCampaignAudience,
 } from '@learncard/types';
 
@@ -13,6 +14,7 @@ import { constructUri, getUriParts } from '@helpers/uri.helpers';
 import type { CampaignAudienceQuery } from 'types/campaign';
 import {
     assertCampaignEditable,
+    adultProfilePredicate,
     campaignAgePredicate,
     campaignTimeParams,
     lockCampaign,
@@ -91,11 +93,28 @@ export const buildCampaignAudienceQuery = (
     }
 };
 
+/** Resolve missing input identifiers separately from age-based exclusion. */
+const missingDids = async (
+    source: CampaignAudienceSource,
+    domain: string,
+    transaction?: ManagedTransaction
+): Promise<string[]> => {
+    if (source.type !== 'dids') return [];
+    const query = `UNWIND $dids AS did
+        OPTIONAL MATCH (p:Profile) WHERE p.did = did OR ($didWebPrefix + p.profileId) = did
+        WITH did, count(p) AS matches WHERE matches = 0 RETURN did`;
+    const params = { dids: [...new Set(source.dids)], didWebPrefix: getDidWeb(domain, '') };
+    const result = await (transaction
+        ? transaction.run(query, params)
+        : neogma.queryRunner.run(query, params));
+    return result.records.map(row => row.get('did') as string);
+};
+
 export const previewCampaignAudience = async (
     campaignId: string,
     source: CampaignAudienceSource,
     domain: string
-): Promise<number> => {
+): Promise<CampaignAudienceResult> => {
     await getCampaign(campaignId);
     const query = buildCampaignAudienceQuery(source, domain);
     const result = await traceDb('campaign:previewAudience', () =>
@@ -105,39 +124,52 @@ export const previewCampaignAudience = async (
             { ...query.params, campaignId, ...campaignTimeParams() }
         )
     );
-    return result.records[0]!.get('count').toNumber();
+    return {
+        count: result.records[0]!.get('count').toNumber(),
+        added: 0,
+        notFound: await missingDids(source, domain),
+    };
 };
 
 export const addCampaignAudience = async (
     campaignId: string,
     source: CampaignAudienceSource,
     domain: string
-): Promise<number> => {
+): Promise<CampaignAudienceResult> => {
     const query = buildCampaignAudienceQuery(source, domain);
     return withCampaignTransaction('campaign:addAudience', async transaction => {
         assertCampaignEditable(await lockCampaign(transaction, campaignId));
+        const notFound = await missingDids(source, domain, transaction);
         const result = await transaction.run(
             `${query.match} WITH DISTINCT p MATCH (c:Campaign {id: $campaignId})
              WHERE ${campaignAgePredicate}
+             OPTIONAL MATCH (p)-[existing:IN_CAMPAIGN_AUDIENCE]->(c)
+             WITH p, c, existing IS NULL AS isNew
              MERGE (p)-[audience:IN_CAMPAIGN_AUDIENCE]->(c)
              ON CREATE SET audience.addedAt = $now, audience.source = $source
-             RETURN count(p) AS count`,
+             RETURN count(p) AS count, sum(CASE WHEN isNew THEN 1 ELSE 0 END) AS added`,
             { ...query.params, campaignId, source: source.type, ...campaignTimeParams() }
         );
-        return result.records[0]!.get('count').toNumber();
+        return {
+            count: result.records[0]!.get('count').toNumber(),
+            added: result.records[0]!.get('added').toNumber(),
+            notFound,
+        };
     });
 };
 
 export const pageCampaignAudience = async (
     campaignId: string,
     cursor?: string,
-    limit = 100
+    limit = 100,
+    deliveryChannel?: 'email'
 ): Promise<PaginatedCampaignAudience> => {
     await getCampaign(campaignId);
     const result = await traceDb('campaign:pageAudience', () =>
         neogma.queryRunner.run(
             `MATCH (p:Profile)-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
          WHERE ($cursor IS NULL OR p.profileId > $cursor) AND ${campaignAgePredicate}
+         ${deliveryChannel === 'email' ? `AND ${adultProfilePredicate} AND coalesce(p.announcementEmailOptOut, false) = false` : ''}
          RETURN DISTINCT p.profileId AS profileId, p.did AS did ORDER BY profileId LIMIT $limit`,
             { campaignId, cursor: cursor ?? null, limit: int(limit + 1), ...campaignTimeParams() }
         )

package/src/accesslayer/campaign/create.ts

@@ -13,13 +13,15 @@ import { campaignProperties } from './shared';
 
 export const createCampaign = async (
     input: CreateCampaignInput,
-    createdByProfileId: string
+    createdByProfileId: string,
+    tenantId?: string
 ): Promise<Campaign> => {
     const parsed = CreateCampaignInputValidator.parse(input);
     const now = new Date().toISOString();
     const campaign = CampaignValidator.parse({
         ...parsed,
-        message: { ...parsed.message, id: parsed.id },
+        message: parsed.message ? { ...parsed.message, id: parsed.id } : undefined,
+        tenantId,
         createdAt: now,
         updatedAt: now,
     });

package/src/accesslayer/campaign/delivery.ts

@@ -0,0 +1,66 @@
+import type { LCNNotification } from '@learncard/types';
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+import type { ProfileType } from 'types/profile';
+import {
+    campaignAgePredicate,
+    campaignTimeParams,
+    liveCampaignPredicate,
+    parseCampaign,
+    withCampaignTransaction,
+} from './shared';
+
+/** Recheck eligibility at enqueue and delivery time; queued work can outlive a pause. */
+export const getCampaignDeliveryRecipient = async (
+    campaignId: string,
+    campaignCreatedAt: string,
+    profileId: string
+): Promise<ProfileType | undefined> => {
+    const result = await traceDb('campaign:deliveryRecipient', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {profileId: $profileId})-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
+             WHERE c.createdAt = $campaignCreatedAt AND ${liveCampaignPredicate}
+               AND ${campaignAgePredicate}
+               AND coalesce(p.announcementPushOptOut, false) = false
+             OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+             WITH p, c, state WHERE state.notifiedAt IS NULL
+             RETURN properties(p) AS profile, c.definition AS definition`,
+            { campaignId, campaignCreatedAt, profileId, ...campaignTimeParams() }
+        )
+    );
+    const row = result.records[0];
+    if (!row || !parseCampaign(row.get('definition')).channels.includes('notify')) return undefined;
+    return row.get('profile') as ProfileType;
+};
+
+/** Only durable inbox acknowledgement counts as notified; enqueueing alone does not. */
+export const acknowledgeCampaignNotification = async (
+    notification: LCNNotification
+): Promise<void> => {
+    const metadata = notification.data?.metadata;
+    if (notification.type !== 'ANNOUNCEMENT' || metadata?.campaignTestId) return;
+    if (!metadata?.campaignId || !metadata.campaignCreatedAt || !notification.to.profileId)
+        throw new Error('Campaign delivery is missing its identity');
+
+    await withCampaignTransaction('campaign:acknowledgeNotification', async transaction => {
+        const params = {
+            campaignId: metadata.campaignId,
+            campaignCreatedAt: metadata.campaignCreatedAt,
+            profileId: notification.to.profileId,
+            ...campaignTimeParams(),
+        };
+        // Use the same profile lock as engagement writes to keep one state relationship.
+        await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})
+             SET p.campaignStateLock = coalesce(p.campaignStateLock, 0) + 1`,
+            params
+        );
+        await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
+             WHERE c.createdAt = $campaignCreatedAt
+             MERGE (p)-[state:CAMPAIGN_STATE]->(c)
+             SET state.notifiedAt = coalesce(state.notifiedAt, $now)`,
+            params
+        );
+    });
+};

package/src/accesslayer/campaign/dispatch.test.ts

@@ -0,0 +1,59 @@
+import { beforeEach, expect, it, vi } from 'vitest';
+import { CampaignValidator } from '@learncard/types';
+import { int } from 'neo4j-driver';
+
+const mocks = vi.hoisted(() => ({ run: vi.fn() }));
+vi.mock('@instance', () => ({ neogma: { queryRunner: { run: mocks.run } } }));
+vi.mock('@helpers/campaign-notifications.helpers', () => ({ canDispatchCampaign: () => true }));
+import { getCampaignDispatchPreview, MAX_CONFIRMED_DISPATCH_RECIPIENTS } from './dispatch';
+
+const definition = JSON.stringify(
+    CampaignValidator.parse({
+        id: 'campaign',
+        name: 'Campaign',
+        status: 'live',
+        channels: ['notify'],
+        notification: { title: 'Title', body: 'Body' },
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+    })
+);
+const recipients = (ids: string[]) => {
+    const row = {
+        definition,
+        recipients: ids,
+        revision: int(0),
+        audience: int(ids.length),
+        notified: int(0),
+    };
+    mocks.run.mockResolvedValue({ records: [{ get: (key: keyof typeof row) => row[key] }] });
+};
+beforeEach(() => mocks.run.mockReset());
+
+it('fingerprints identities independent of row ordering while detecting equal-count swaps', async () => {
+    recipients(['b', 'a']);
+    const first = await getCampaignDispatchPreview('campaign');
+    recipients(['a', 'b']);
+    expect(await getCampaignDispatchPreview('campaign')).toEqual(first);
+    recipients(['a', 'c']);
+    const swapped = await getCampaignDispatchPreview('campaign');
+    expect(swapped.recipientCount).toBe(first.recipientCount);
+    expect(swapped.previewToken).not.toBe(first.previewToken);
+});
+it('bounds collection before transfer and refuses to produce a token for an overflowing set', async () => {
+    recipients(Array.from({ length: MAX_CONFIRMED_DISPATCH_RECIPIENTS }, (_, i) => `profile-${i}`));
+    await expect(getCampaignDispatchPreview('campaign')).resolves.toMatchObject({
+        recipientCount: 10_000,
+    });
+    const [query, params] = mocks.run.mock.calls[0]!;
+    expect(params.recipientLimit.toNumber()).toBe(10_001);
+    expect(query.indexOf('LIMIT $recipientLimit')).toBeLessThan(
+        query.indexOf('collect(profileId)')
+    );
+    recipients(
+        Array.from({ length: MAX_CONFIRMED_DISPATCH_RECIPIENTS + 1 }, (_, i) => `profile-${i}`)
+    );
+    await expect(getCampaignDispatchPreview('campaign')).rejects.toMatchObject({
+        code: 'BAD_REQUEST',
+    });
+});