@learncard/network-brain-service 4.1.2 → 5.0.0

package/src/accesslayer/campaign/dispatch.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+import { createHash } from 'node:crypto';
+import { TRPCError } from '@trpc/server';
+import { int, type ManagedTransaction } from 'neo4j-driver';
+import type { Campaign, CampaignDispatchPreview } from '@learncard/types';
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+import { canDispatchCampaign } from '@helpers/campaign-notifications.helpers';
+import {
+    campaignAgePredicate,
+    adultProfilePredicate,
+    campaignTimeParams,
+    parseCampaign,
+    withCampaignTransaction,
+} from './shared';
+
+export const MAX_CONFIRMED_DISPATCH_RECIPIENTS = 10_000;
+
+/** Review eligible inbox and email recipients using the delivery predicates. */
+const readPreview = async (
+    campaignId: string,
+    transaction?: ManagedTransaction
+): Promise<{ campaign: Campaign; preview: CampaignDispatchPreview }> => {
+    const params = {
+        campaignId,
+        ...campaignTimeParams(),
+        recipientLimit: int(MAX_CONFIRMED_DISPATCH_RECIPIENTS + 1),
+    };
+    const query = `MATCH (c:Campaign {id: $campaignId})
+        OPTIONAL MATCH (p:Profile)-[:IN_CAMPAIGN_AUDIENCE]->(c)
+        OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+        WITH c, count(DISTINCT p) AS audience,
+          count(DISTINCT CASE WHEN state.notifiedAt IS NOT NULL THEN p END) AS notified
+        CALL {
+          WITH c
+          MATCH (p:Profile)-[:IN_CAMPAIGN_AUDIENCE]->(c)
+          OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+          WITH c, p, state WHERE ${campaignAgePredicate} AND state.notifiedAt IS NULL
+            AND coalesce(p.announcementPushOptOut, false) = false
+          WITH DISTINCT p.profileId AS profileId LIMIT $recipientLimit
+          RETURN collect(profileId) AS recipients
+        }
+        RETURN c.definition AS definition, coalesce(c.lockVersion, 0) AS revision,
+          audience, notified, recipients`;
+    const result = await traceDb('campaign:dispatchPreview', () =>
+        transaction ? transaction.run(query, params) : neogma.queryRunner.run(query, params)
+    );
+    const row = result.records[0];
+    if (!row) throw new TRPCError({ code: 'NOT_FOUND', message: 'Campaign not found' });
+    const campaign = parseCampaign(row.get('definition'));
+    const recipients =
+        campaign.channels.includes('notify') && campaign.notification
+            ? (row.get('recipients') as string[])
+            : [];
+    let emailRecipients: { profileId: string; email: string }[] = [];
+    if (campaign.channels.includes('email') && campaign.email) {
+        // Match claimCampaignEmail: adults, opt-in, one verified primary contact,
+        // and no previous claim/acceptance. Include the address in the review digest.
+        const emailQuery = `MATCH (p:Profile)-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
+            WHERE ${adultProfilePredicate} AND coalesce(p.announcementEmailOptOut, false) = false
+            OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+            WITH p, state WHERE state.emailClaimedAt IS NULL AND state.emailedAt IS NULL
+            MATCH (p)-[:HAS_CONTACT_METHOD]->(email:ContactMethod)
+            WHERE email.type = 'email' AND email.isPrimary = true AND email.isVerified = true
+            WITH p, collect(email) AS emails WHERE size(emails) = 1
+            RETURN p.profileId AS profileId, emails[0].value AS email LIMIT $recipientLimit`;
+        const emails = await (transaction
+            ? transaction.run(emailQuery, params)
+            : neogma.queryRunner.run(emailQuery, params));
+        if (emails.records.length > MAX_CONFIRMED_DISPATCH_RECIPIENTS)
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Reduce the email audience and preview again',
+            });
+        emailRecipients = emails.records
+            .map(record => ({
+                profileId: record.get('profileId') as string,
+                email: record.get('email') as string,
+            }))
+            .filter(recipient => z.email().safeParse(recipient.email).success)
+            .sort((a, b) => a.profileId.localeCompare(b.profileId));
+    }
+    // Bound collection in Cypher before transferring or sorting IDs. Never authorize a partial set.
+    if (recipients.length > MAX_CONFIRMED_DISPATCH_RECIPIENTS)
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: `Confirmed dispatch supports at most ${MAX_CONFIRMED_DISPATCH_RECIPIENTS} eligible recipients; reduce the audience and preview again`,
+        });
+    recipients.sort();
+    let blockedReason: CampaignDispatchPreview['blockedReason'];
+    const recipientCount = new Set([...recipients, ...emailRecipients.map(item => item.profileId)])
+        .size;
+    if (recipientCount > MAX_CONFIRMED_DISPATCH_RECIPIENTS)
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Reduce the audience and preview again',
+        });
+    if (!canDispatchCampaign(campaign, params.now)) {
+        blockedReason =
+            campaign.status !== 'live'
+                ? 'not_live'
+                : !(
+                        (campaign.channels.includes('notify') && campaign.notification) ||
+                        (campaign.channels.includes('email') && campaign.email)
+                    )
+                  ? 'notify_disabled'
+                  : campaign.startsAt && campaign.startsAt > params.now
+                    ? 'not_started'
+                    : 'ended';
+    } else if (!recipientCount) blockedReason = 'no_recipients';
+    // A digest avoids exposing recipient identities and detects equal-count membership swaps.
+    // Revision changes on audience edits, definition changes, or a confirmed dispatch.
+    const previewToken = createHash('sha256')
+        .update(
+            JSON.stringify({
+                definition: row.get('definition'),
+                revision: row.get('revision').toString(),
+                recipients,
+                emailRecipients,
+                blockedReason,
+            })
+        )
+        .digest('hex');
+    return {
+        campaign,
+        preview: {
+            campaignId,
+            audienceCount: row.get('audience').toNumber(),
+            alreadyNotifiedCount: row.get('notified').toNumber(),
+            recipientCount: blockedReason ? 0 : recipientCount,
+            notificationRecipientCount: blockedReason ? 0 : recipients.length,
+            emailRecipientCount: blockedReason ? 0 : emailRecipients.length,
+            previewToken,
+            ...(blockedReason ? { blockedReason } : {}),
+        },
+    };
+};
+
+export const getCampaignDispatchPreview = async (
+    campaignId: string
+): Promise<CampaignDispatchPreview> => (await readPreview(campaignId)).preview;
+
+/** Recheck and consume a confirmation once, serialized with campaign/audience edits. */
+export const authorizeConfirmedCampaignDispatch = async (
+    campaignId: string,
+    expectedPreviewToken: string
+): Promise<Campaign> =>
+    withCampaignTransaction('campaign:confirmDispatch', async transaction => {
+        // Acquire the same node write lock as campaign/audience edits without changing their revision yet.
+        await transaction.run(
+            `MATCH (c:Campaign {id: $campaignId})
+        SET c.dispatchCheckLock = coalesce(c.dispatchCheckLock, 0) + 1`,
+            { campaignId }
+        );
+        const { campaign, preview } = await readPreview(campaignId, transaction);
+        if (preview.previewToken !== expectedPreviewToken)
+            throw new TRPCError({
+                code: 'CONFLICT',
+                message: 'Campaign or recipients changed; preview again',
+            });
+        if (preview.blockedReason)
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Campaign has no eligible notification recipients now',
+            });
+        await transaction.run(
+            `MATCH (c:Campaign {id: $campaignId})
+        SET c.lockVersion = coalesce(c.lockVersion, 0) + 1`,
+            { campaignId }
+        );
+        return campaign;
+    });

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

@@ -0,0 +1,73 @@
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    run: vi.fn(),
+    campaign: { id: 'news', channels: ['email'], email: { title: 'News' } },
+}));
+vi.mock('./shared', () => ({
+    adultProfilePredicate: 'true',
+    liveCampaignPredicate: 'true',
+    campaignTimeParams: () => ({ now: '2026-01-01T00:00:00Z' }),
+    parseCampaign: () => mocks.campaign,
+    withCampaignTransaction: async (_name: string, work: (tx: unknown) => Promise<unknown>) =>
+        work({ run: mocks.run }),
+}));
+vi.mock('../../models/campaign-constraints', () => ({
+    ensureCampaignConstraints: vi.fn().mockResolvedValue(undefined),
+}));
+import { claimCampaignEmail } from './email';
+
+beforeEach(() => {
+    vi.resetAllMocks();
+    mocks.run.mockImplementation(async (query: string) => ({
+        records: query.includes('RETURN c.definition')
+            ? [
+                  {
+                      get: (key: string) =>
+                          (
+                              ({
+                                  definition: '{}',
+                                  email: 'adult@example.com',
+                                  locale: 'es',
+                                  unsubscribeId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+                              }) as Record<string, string>
+                          )[key],
+                  },
+              ]
+            : [],
+    }));
+});
+
+it('does not write a reservation when preparation fails', async () => {
+    const prepare = vi.fn().mockRejectedValue(new Error('Cannot render'));
+    await expect(claimCampaignEmail('news', 'created', 'adult', false, prepare)).rejects.toThrow(
+        'Cannot render'
+    );
+    expect(prepare).toHaveBeenCalledWith({
+        campaign: mocks.campaign,
+        email: 'adult@example.com',
+        locale: 'es',
+        unsubscribeId: 'aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    });
+    expect(mocks.run.mock.calls.some(([query]) => query.includes('SET state.emailClaimedAt'))).toBe(
+        false
+    );
+});
+
+it('prepares the selected recipient before writing its reservation', async () => {
+    const prepare = vi.fn(async () => {
+        expect(
+            mocks.run.mock.calls.some(([query]) => query.includes('SET state.emailClaimedAt'))
+        ).toBe(false);
+    });
+    await claimCampaignEmail('news', 'created', 'adult', false, prepare);
+    expect(prepare).toHaveBeenCalledOnce();
+    expect(mocks.run.mock.calls.at(-1)?.[0]).toContain('SET state.emailClaimedAt');
+});
+
+it('does not prepare an ineligible recipient', async () => {
+    mocks.run.mockResolvedValue({ records: [] });
+    const prepare = vi.fn();
+    expect(await claimCampaignEmail('news', 'created', 'adult', false, prepare)).toBeUndefined();
+    expect(prepare).not.toHaveBeenCalled();
+});

package/src/accesslayer/campaign/email.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import type { Campaign } from '@learncard/types';
+import { ensureCampaignConstraints } from '../../models/campaign-constraints';
+import {
+    adultProfilePredicate,
+    campaignTimeParams,
+    liveCampaignPredicate,
+    parseCampaign,
+    withCampaignTransaction,
+} from './shared';
+
+export type CampaignEmailRecipient = {
+    campaign: Campaign;
+    email: string;
+    unsubscribeId: string;
+    locale?: string;
+};
+
+/** Reserve before external I/O. A lost acknowledgement remains reserved and is never retried automatically. */
+export const claimCampaignEmail = async (
+    campaignId: string,
+    campaignCreatedAt: string,
+    profileId: string,
+    test = false,
+    prepare?: (recipient: CampaignEmailRecipient) => Promise<void>
+): Promise<CampaignEmailRecipient | undefined> => {
+    await ensureCampaignConstraints();
+    return withCampaignTransaction('campaign:claimEmail', async transaction => {
+        const params = { campaignId, campaignCreatedAt, profileId, ...campaignTimeParams() };
+        await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})
+            SET p.campaignStateLock = coalesce(p.campaignStateLock, 0) + 1,
+                p.campaignUnsubscribeId = coalesce(p.campaignUnsubscribeId, randomUUID())`,
+            params
+        );
+        const result = await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId}), (c:Campaign {id: $campaignId})
+             WHERE c.createdAt = $campaignCreatedAt AND ${adultProfilePredicate}
+               AND coalesce(p.announcementEmailOptOut, false) = false
+               ${test ? '' : `AND ${liveCampaignPredicate} AND EXISTS { MATCH (p)-[:IN_CAMPAIGN_AUDIENCE]->(c) }`}
+             MATCH (p)-[:HAS_CONTACT_METHOD]->(email:ContactMethod)
+             WHERE email.type = 'email' AND email.isPrimary = true AND email.isVerified = true
+             OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+             WITH p, c, email, state
+             ${test ? '' : 'WHERE state.emailClaimedAt IS NULL AND state.emailedAt IS NULL'}
+             WITH p, c, email ORDER BY email.id LIMIT 2
+             RETURN c.definition AS definition, email.value AS email, p.locale AS locale,
+                    p.campaignUnsubscribeId AS unsubscribeId`,
+            params
+        );
+        // Ambiguous primary contacts fail closed, as do malformed legacy addresses.
+        if (result.records.length !== 1) return undefined;
+        const row = result.records[0]!;
+        const campaign = parseCampaign(row.get('definition'));
+        const email = z.email().safeParse(row.get('email'));
+        if (!email.success || !campaign.channels.includes('email') || !campaign.email)
+            return undefined;
+        const recipient = {
+            campaign,
+            email: email.data,
+            unsubscribeId: row.get('unsubscribeId') as string,
+            locale: row.get('locale') ?? undefined,
+        };
+        // Local preparation only: no provider send inside a retriable transaction.
+        // A render failure aborts before writing the durable claim.
+        await prepare?.(recipient);
+        if (!test)
+            await transaction.run(
+                `MATCH (p:Profile {profileId: $profileId}), (c:Campaign {id: $campaignId})
+             MERGE (p)-[state:CAMPAIGN_STATE]->(c) SET state.emailClaimedAt = $now`,
+                params
+            );
+        return recipient;
+    });
+};
+
+/** Provider acceptance only; a claim alone is not an emailed statistic. */
+export const acknowledgeCampaignEmail = async (
+    campaignId: string,
+    campaignCreatedAt: string,
+    profileId: string
+): Promise<void> => {
+    await withCampaignTransaction('campaign:acknowledgeEmail', async transaction => {
+        await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})-[state:CAMPAIGN_STATE]->(c:Campaign {id: $campaignId})
+             WHERE c.createdAt = $campaignCreatedAt AND state.emailClaimedAt IS NOT NULL
+             SET state.emailedAt = coalesce(state.emailedAt, $now)`,
+            { campaignId, campaignCreatedAt, profileId, ...campaignTimeParams() }
+        );
+    });
+};

package/src/accesslayer/campaign/preferences.ts

@@ -0,0 +1,53 @@
+import { TRPCError } from '@trpc/server';
+import type { AnnouncementPreferences } from '@learncard/types';
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+
+/** Resolve the durable recipient directly so renames and reused names cannot redirect opt-outs. */
+export const unsubscribeCampaignRecipient = async (unsubscribeId: string): Promise<void> => {
+    await traceDb('campaign:unsubscribeRecipient', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {campaignUnsubscribeId: $unsubscribeId})
+             SET p.announcementEmailOptOut = true`,
+            { unsubscribeId }
+        )
+    );
+};
+
+/** Private preferences are read from the graph, never a cached public profile. */
+export const getAnnouncementPreferences = async (
+    profileId: string
+): Promise<AnnouncementPreferences> => {
+    const result = await traceDb('campaign:preferences', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {profileId: $profileId})
+         RETURN coalesce(p.announcementEmailOptOut, false) AS email,
+                coalesce(p.announcementPushOptOut, false) AS push`,
+            { profileId }
+        )
+    );
+    const row = result.records[0];
+    if (!row) throw new TRPCError({ code: 'NOT_FOUND', message: 'Profile not found' });
+    return { announcementEmailOptOut: row.get('email'), announcementPushOptOut: row.get('push') };
+};
+
+/** Patch only supplied choices so concurrent email and push updates cannot clobber each other. */
+export const updateAnnouncementPreferences = async (
+    profileId: string,
+    updates: Partial<AnnouncementPreferences>
+): Promise<AnnouncementPreferences> => {
+    const properties = Object.fromEntries(
+        Object.entries(updates).filter(
+            ([key, value]) =>
+                ['announcementEmailOptOut', 'announcementPushOptOut'].includes(key) &&
+                typeof value === 'boolean'
+        )
+    );
+    await traceDb('campaign:updatePreferences', () =>
+        neogma.queryRunner.run('MATCH (p:Profile {profileId: $profileId}) SET p += $properties', {
+            profileId,
+            properties,
+        })
+    );
+    return getAnnouncementPreferences(profileId);
+};

package/src/accesslayer/campaign/read.ts

@@ -73,7 +73,7 @@ export const getLiveCampaignsForProfile = async (
             });
             return [];
         }
-        if (!campaign.channels.includes('inApp') || !campaign.message.enabled) return [];
+        if (!campaign.channels.includes('inApp') || !campaign.message?.enabled) return [];
         const state = Object.fromEntries(
             Object.entries(record.get('state') ?? {}).map(([key, value]) => [
                 key,
@@ -104,6 +104,7 @@ export const getCampaignStats = async (campaignId: string): Promise<CampaignStat
          OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
          RETURN count(DISTINCT p) AS audience,
            count(DISTINCT CASE WHEN audience.source = 'selfEnrolled' THEN p END) AS enrolled,
+           count(DISTINCT CASE WHEN state.emailedAt IS NOT NULL THEN p END) AS emailed,
            count(DISTINCT CASE WHEN state.notifiedAt IS NOT NULL THEN p END) AS notified,
            count(DISTINCT CASE WHEN state.firstShownAt IS NOT NULL THEN p END) AS shown,
            count(DISTINCT CASE WHEN state.clickedAt IS NOT NULL THEN p END) AS clicked,
@@ -117,6 +118,7 @@ export const getCampaignStats = async (campaignId: string): Promise<CampaignStat
         audience: record.get('audience').toNumber(),
         enrolled: record.get('enrolled').toNumber(),
         notified: record.get('notified').toNumber(),
+        emailed: record.get('emailed').toNumber(),
         shown: record.get('shown').toNumber(),
         clicked: record.get('clicked').toNumber(),
         dismissed: record.get('dismissed').toNumber(),

package/src/accesslayer/campaign/state.ts

@@ -17,7 +17,7 @@ export const enrollInCampaign = async (profileId: string, campaignId: string): P
         if (
             !campaign.selfEnroll ||
             campaign.status !== 'live' ||
-            !campaign.message.enabled ||
+            !campaign.message?.enabled ||
             !campaign.channels.includes('inApp') ||
             (campaign.startsAt && campaign.startsAt > params.now) ||
             (campaign.endsAt && campaign.endsAt <= params.now)

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

@@ -0,0 +1,31 @@
+import { beforeEach, expect, it, vi } from 'vitest';
+import { inAppMessageValidator } from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({ run: vi.fn() }));
+vi.mock('@instance', () => ({ neogma: { queryRunner: { run: mocks.run } } }));
+import { getCampaignTests } from './test';
+
+beforeEach(() => mocks.run.mockReset());
+
+it('isolates malformed JSON and obsolete message schemas from valid private tests', async () => {
+    const id = 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa';
+    const valid = {
+        id,
+        campaignId: 'campaign',
+        message: JSON.stringify({ id: 'test', title: 'Valid' }),
+    };
+    mocks.run.mockResolvedValue({
+        records: [
+            { ...valid, message: '{' },
+            { ...valid, message: JSON.stringify({ id: 'obsolete', presentation: 'removed-type' }) },
+            valid,
+        ].map(row => ({ get: (key: keyof typeof row) => row[key] })),
+    });
+    await expect(getCampaignTests('admin')).resolves.toEqual([
+        {
+            id,
+            campaignId: 'campaign',
+            message: inAppMessageValidator.parse({ id: 'test', title: 'Valid' }),
+        },
+    ]);
+});

package/src/accesslayer/campaign/test.ts

@@ -0,0 +1,75 @@
+import { CampaignTestValidator, type Campaign, type CampaignTest } from '@learncard/types';
+import { TRPCError } from '@trpc/server';
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+
+/** Keep the latest private test per administrator/campaign, without enrolling the administrator. */
+export const queueCampaignInAppTest = async (
+    campaign: Campaign,
+    profileId: string,
+    testId: string
+): Promise<void> => {
+    if (!campaign.message)
+        throw new TRPCError({ code: 'BAD_REQUEST', message: 'Campaign has no in-app message' });
+    const message = { ...campaign.message, id: `campaign-test-${testId}` };
+    const result = await traceDb('campaign:queueTest', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {profileId: $profileId}), (c:Campaign {id: $campaignId})
+             WHERE c.createdAt = $createdAt
+             MERGE (p)-[test:CAMPAIGN_TEST]->(c)
+             SET test.id = $testId, test.message = $message, test.createdAt = $now
+             RETURN test.id AS id`,
+            {
+                profileId,
+                campaignId: campaign.id,
+                createdAt: campaign.createdAt,
+                testId,
+                message: JSON.stringify(message),
+                now: new Date().toISOString(),
+            }
+        )
+    );
+    if (!result.records.length)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Campaign or administrator not found' });
+};
+
+/** Reading does not consume a test; only a renderer acknowledgement removes it. */
+export const getCampaignTests = async (profileId: string): Promise<CampaignTest[]> => {
+    const result = await traceDb('campaign:getTests', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {profileId: $profileId})-[test:CAMPAIGN_TEST]->(c:Campaign)
+             RETURN test.id AS id, c.id AS campaignId, test.message AS message
+             ORDER BY test.createdAt, test.id LIMIT 20`,
+            { profileId }
+        )
+    );
+    return result.records.flatMap(record => {
+        try {
+            const parsed = CampaignTestValidator.safeParse({
+                id: record.get('id'),
+                campaignId: record.get('campaignId'),
+                message: JSON.parse(record.get('message')),
+            });
+            return parsed.success ? [parsed.data] : [];
+        } catch {
+            // A stale or malformed private snapshot must not hide live campaigns or valid tests.
+            return [];
+        }
+    });
+};
+
+/** An acknowledgement of an older snapshot cannot consume a newly queued test. */
+export const acknowledgeCampaignTest = async (
+    profileId: string,
+    campaignId: string,
+    testId: string
+): Promise<boolean> => {
+    await traceDb('campaign:acknowledgeTest', () =>
+        neogma.queryRunner.run(
+            `MATCH (:Profile {profileId: $profileId})-[test:CAMPAIGN_TEST {id: $testId}]->(:Campaign {id: $campaignId})
+             DELETE test`,
+            { profileId, campaignId, testId }
+        )
+    );
+    return true;
+};

package/src/accesslayer/campaign/update.ts

@@ -14,24 +14,35 @@ import {
 } from './shared';
 
 export const updateCampaign = async (input: UpdateCampaignInput): Promise<Campaign> => {
-    const { campaignId, updates } = UpdateCampaignInputValidator.parse(input);
+    const { campaignId, updates, expectedUpdatedAt } = UpdateCampaignInputValidator.parse(input);
     return withCampaignTransaction('campaign:update', async transaction => {
         const existing = await lockCampaign(transaction, campaignId);
+        if (expectedUpdatedAt !== undefined && expectedUpdatedAt !== existing.updatedAt) {
+            throw new TRPCError({
+                code: 'CONFLICT',
+                message: 'Campaign changed since it was loaded. Reload before saving.',
+            });
+        }
         assertCampaignEditable(existing);
-        const message = updates.message ?? existing.message;
+        const message =
+            updates.message === null ? undefined : (updates.message ?? existing.message);
         const result = CampaignValidator.safeParse({
             ...existing,
             ...updates,
             id: campaignId,
-            message: { ...message, id: campaignId },
+            message: message ? { ...message, id: campaignId } : undefined,
             notification:
                 updates.notification === null
                     ? undefined
                     : (updates.notification ?? existing.notification),
+            email: updates.email === null ? undefined : (updates.email ?? existing.email),
             startsAt:
                 updates.startsAt === null ? undefined : (updates.startsAt ?? existing.startsAt),
             endsAt: updates.endsAt === null ? undefined : (updates.endsAt ?? existing.endsAt),
-            updatedAt: new Date().toISOString(),
+            // Every successful write must invalidate a loaded revision, even within one millisecond.
+            updatedAt: new Date(
+                Math.max(Date.now(), Date.parse(existing.updatedAt) + 1)
+            ).toISOString(),
         });
         if (!result.success)
             throw new TRPCError({ code: 'BAD_REQUEST', message: result.error.message });

package/src/accesslayer/consentflowcontract/create.ts

@@ -83,7 +83,14 @@ export const createConsentFlowContract = async ({
                 updatedAt: createdAt,
                 audienceVersion: uniqueRecipientIds.length,
                 expiresAt,
+                currentVersion: 1,
+                status: 'active',
             }),
+            versionId: uuid(),
+            version: 1,
+            contractSnapshot: JSON.stringify(contract),
+            autoboostSnapshot: JSON.stringify(uniqueAutoBoosts),
+            writerSnapshot: JSON.stringify(uniqueWriterIds),
         })
     )
         // Resolve every target before writing; a missing target produces no writes.
@@ -106,6 +113,16 @@ export const createConsentFlowContract = async ({
         .set('contract += $params')
         .raw(
             `
+            CREATE (version:ConsentFlowContractVersion {
+                id: $versionId, version: $version, contract: $contractSnapshot,
+                autoboosts: $autoboostSnapshot, writers: $writerSnapshot,
+                name: $params.name, subtitle: $params.subtitle, description: $params.description,
+                reasonForAccessing: $params.reasonForAccessing, image: $params.image,
+                needsGuardianConsent: $params.needsGuardianConsent, redirectUrl: $params.redirectUrl,
+                frontDoorBoostUri: $params.frontDoorBoostUri, expiresAt: $params.expiresAt,
+                createdAt: $createdAt
+            })
+            CREATE (contract)-[:HAS_VERSION]->(version)
             CREATE (contract)-[:CREATED_BY]->(owner)
             FOREACH (recipient IN recipients |
                 CREATE (contract)-[:SHARES_DATA_WITH {addedAt: $createdAt}]->(recipient))
@@ -129,5 +146,7 @@ export const createConsentFlowContract = async ({
             message: 'Could not find all contract configuration targets',
         });
     }
-    return inflateObject<DbContractType>(created.properties);
+    const createdContract = inflateObject<DbContractType>(created.properties);
+    createdContract.contract = contract;
+    return createdContract;
 };