@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/campaign-queue.helpers.ts

@@ -0,0 +1,122 @@
+import {
+    CampaignEmailDeliveryError,
+    prepareCampaignEmailDelivery,
+    sendCampaignEmail,
+} from './campaign-email.helpers';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
+import { TRPCError } from '@trpc/server';
+import { CampaignDispatchJobValidator, type CampaignDispatchJob } from 'types/campaign';
+import { environment } from '@environment';
+import { authorizeConfirmedCampaignDispatch } from '@accesslayer/campaign/dispatch';
+import { getCampaign } from '@accesslayer/campaign/read';
+import { pageCampaignAudience } from '@accesslayer/campaign/audience';
+import { getCampaignDeliveryRecipient } from '@accesslayer/campaign/delivery';
+import { trace } from '@tracing';
+import {
+    buildCampaignNotification,
+    canDispatchCampaign,
+    enqueueCampaignNotification,
+} from './campaign-notifications.helpers';
+
+const sqs = new SQSClient({ region: environment.AWS_REGION || 'us-east-1' });
+
+/** Local fallback is awaited, including delays; use SQS for durable production waves. */
+export const addCampaignDispatchToQueue = async (
+    rawJob: CampaignDispatchJob,
+    delaySeconds = 0
+): Promise<void> => {
+    const job = CampaignDispatchJobValidator.parse(rawJob);
+    if (environment.IS_OFFLINE || !environment.CAMPAIGN_QUEUE_URL) {
+        if (delaySeconds) await delay(delaySeconds * 1000);
+        await processCampaignDispatchJob(job);
+        return;
+    }
+    await sqs.send(
+        new SendMessageCommand({
+            QueueUrl: environment.CAMPAIGN_QUEUE_URL,
+            MessageBody: JSON.stringify(job),
+            DelaySeconds: delaySeconds,
+        })
+    );
+};
+
+export const dispatchCampaign = async (
+    campaignId: string,
+    expectedPreviewToken?: string
+): Promise<{ dispatchId: string }> => {
+    // Keep existing SDK callers compatible; the composer always supplies its reviewed token.
+    const campaign = expectedPreviewToken
+        ? await authorizeConfirmedCampaignDispatch(campaignId, expectedPreviewToken)
+        : await getCampaign(campaignId);
+    if (!canDispatchCampaign(campaign))
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Campaign must be live, in its time window, and have a delivery channel',
+        });
+    const dispatchId = randomUUID();
+    if (campaign.channels.includes('email')) await prepareCampaignEmailDelivery();
+    for (const channel of ['notify', 'email'] as const) {
+        if (campaign.channels.includes(channel))
+            await addCampaignDispatchToQueue({
+                campaignId,
+                campaignCreatedAt: campaign.createdAt,
+                dispatchId,
+                channel,
+            });
+    }
+    return { dispatchId };
+};
+
+export const processCampaignDispatchJob = async (rawJob: CampaignDispatchJob): Promise<void> =>
+    trace('worker', 'campaign:dispatch', async () => {
+        const job = CampaignDispatchJobValidator.parse(rawJob);
+        let campaign;
+        try {
+            campaign = await getCampaign(job.campaignId);
+        } catch (error) {
+            if (error instanceof TRPCError && error.code === 'NOT_FOUND') return;
+            throw error;
+        }
+        if (campaign.createdAt !== job.campaignCreatedAt || !canDispatchCampaign(campaign)) return;
+        if (!campaign.channels.includes(job.channel)) return;
+        const emailAdapter =
+            job.channel === 'email' ? await prepareCampaignEmailDelivery() : undefined;
+        const pageSize =
+            job.channel === 'email'
+                ? environment.CAMPAIGN_EMAIL_PAGE_SIZE
+                : environment.CAMPAIGN_DISPATCH_PAGE_SIZE;
+        const page = await pageCampaignAudience(
+            job.campaignId,
+            job.afterProfileId,
+            pageSize,
+            job.channel === 'email' ? 'email' : undefined
+        );
+        for (const { profileId } of page.records) {
+            if (job.channel === 'email') {
+                try {
+                    await sendCampaignEmail(campaign, profileId, false, emailAdapter);
+                } catch (error) {
+                    // Only post-claim failures can be skipped safely. Configuration,
+                    // rendering and database failures retry the page without consuming claims.
+                    if (!(error instanceof CampaignEmailDeliveryError)) throw error;
+                    console.error('Campaign email delivery failed; reservation retained');
+                }
+                continue;
+            }
+            const recipient = await getCampaignDeliveryRecipient(
+                job.campaignId,
+                job.campaignCreatedAt,
+                profileId
+            );
+            if (!recipient) continue;
+            await enqueueCampaignNotification(await buildCampaignNotification(campaign, recipient));
+        }
+        if (page.records.length === pageSize) {
+            await addCampaignDispatchToQueue(
+                { ...job, afterProfileId: page.records.at(-1)!.profileId },
+                environment.CAMPAIGN_DISPATCH_DELAY_SECONDS
+            );
+        }
+    });

package/src/helpers/campaign-unsubscribe-page.ts

@@ -0,0 +1,107 @@
+const messages = {
+    en: {
+        title: 'Email announcements',
+        confirm: 'Stop receiving email announcements for your account?',
+        success: 'You’re unsubscribed from email announcements.',
+        invalid: 'This link is invalid. Try a link from a newer email.',
+        error: 'We couldn’t update your preferences. Please try again.',
+        unsubscribe: 'Unsubscribe',
+        retry: 'Try Again',
+    },
+    es: {
+        title: 'Anuncios por correo electrónico',
+        confirm: '¿Quieres dejar de recibir anuncios por correo electrónico?',
+        success: 'Ya no recibirás anuncios por correo electrónico.',
+        invalid: 'Este enlace no es válido. Prueba un enlace de un correo más reciente.',
+        error: 'No pudimos actualizar tus preferencias. Inténtalo de nuevo.',
+        unsubscribe: 'Cancelar suscripción',
+        retry: 'Intentar de nuevo',
+    },
+    fr: {
+        title: 'Annonces par e-mail',
+        confirm: 'Ne plus recevoir d’annonces par e-mail pour votre compte ? ',
+        success: 'Vous ne recevrez plus d’annonces par e-mail.',
+        invalid: 'Ce lien est invalide. Essayez un lien provenant d’un e-mail plus récent.',
+        error: 'Vos préférences n’ont pas pu être mises à jour. Veuillez réessayer.',
+        unsubscribe: 'Se désinscrire',
+        retry: 'Réessayer',
+    },
+    ar: {
+        title: 'إعلانات البريد الإلكتروني',
+        confirm: 'هل تريد إيقاف تلقي إعلانات البريد الإلكتروني لحسابك؟',
+        success: 'تم إلغاء اشتراكك في إعلانات البريد الإلكتروني.',
+        invalid: 'هذا الرابط غير صالح. جرّب رابطًا من رسالة بريد إلكتروني أحدث.',
+        error: 'تعذر تحديث تفضيلاتك. يرجى المحاولة مرة أخرى.',
+        unsubscribe: 'إلغاء الاشتراك',
+        retry: 'حاول مرة أخرى',
+    },
+};
+
+/** Standalone anonymous browser flow with no external assets or telemetry. */
+export const renderCampaignUnsubscribePage = (
+    state: 'confirm' | 'success' | 'invalid' | 'error',
+    token?: string,
+    language = 'en'
+): string => {
+    const requested = language.toLowerCase().split(/[-,;]/)[0] ?? 'en';
+    const locale = Object.hasOwn(messages, requested) ? (requested as keyof typeof messages) : 'en';
+    const copy = messages[locale];
+    const safeToken = token && /^[A-Za-z0-9_-]{1,2048}$/.test(token) ? token : undefined;
+    const content = {
+        success: `<p role="status">${copy.success}</p>`,
+        error: `<p role="alert">${copy.error}</p>`,
+        invalid: `<p role="alert">${copy.invalid}</p>`,
+        confirm: `<p>${copy.confirm}</p>`,
+    }[state];
+    const form =
+        state !== 'success' && safeToken
+            ? `<form method="post" action="/campaigns/unsubscribe/browser">
+            <input type="hidden" name="token" value="${safeToken}">
+            <button type="submit">${state === 'error' ? copy.retry : copy.unsubscribe}</button>
+           </form>`
+            : '';
+    return `<!doctype html>
+<html lang="${locale}" dir="${locale === 'ar' ? 'rtl' : 'ltr'}">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="referrer" content="no-referrer">
+    <title>${copy.title}</title>
+    <style>
+        body {
+            margin: 0;
+            background: #EFF0F5;
+            color: #18224E;
+            font-family: system-ui, sans-serif;
+            min-height: 100vh;
+            display: grid;
+            place-items: center;
+        }
+        main {
+            box-sizing: border-box;
+            background: white;
+            border-radius: 20px;
+            padding: 32px;
+            margin: 24px;
+            max-width: 480px;
+            text-align: center;
+        }
+        h1 { font-size: 24px; }
+        p { color: #6F7590; line-height: 1.6; }
+        button {
+            background: #18224E;
+            color: white;
+            border: 0;
+            border-radius: 20px;
+            padding: 12px 24px;
+            font: inherit;
+            cursor: pointer;
+        }
+        button:focus-visible { outline: 3px solid #059669; outline-offset: 3px; }
+    </style>
+</head>
+<body>
+    <main><h1>${copy.title}</h1>${content}${form}</main>
+</body>
+</html>`;
+};

package/src/helpers/campaign-unsubscribe.helpers.ts

@@ -0,0 +1,56 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { TRPCError } from '@trpc/server';
+import { environment } from '@environment';
+import { unsubscribeCampaignRecipient } from '@accesslayer/campaign/preferences';
+
+const recipientIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+const secret = (): string => {
+    const value = environment.CAMPAIGN_UNSUBSCRIBE_SECRET;
+    if (!value || Buffer.byteLength(value) < 32)
+        throw new Error('Campaign unsubscribe secret requires at least 32 bytes');
+    return value;
+};
+
+/** Opaque, purpose-separated bearer token; it authorizes email opt-out only. */
+export const signCampaignUnsubscribeToken = (unsubscribeId: string, campaignId: string): string => {
+    if (!recipientIdPattern.test(unsubscribeId)) throw new Error('Invalid unsubscribe recipient');
+    const payload = `v2.${unsubscribeId}.${campaignId}`;
+    const signature = createHmac('sha256', secret())
+        .update(`campaign-unsubscribe:${payload}`)
+        .digest('base64url');
+    return Buffer.from(`${payload}.${signature}`).toString('base64url');
+};
+
+export const verifyCampaignUnsubscribeToken = (
+    token: string
+): { unsubscribeId: string; campaignId: string } => {
+    const invalid = (): never => {
+        throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid unsubscribe link' });
+    };
+    if (!/^[A-Za-z0-9_-]{1,2048}$/.test(token)) return invalid();
+    const decoded = Buffer.from(token, 'base64url').toString('utf8');
+    if (Buffer.from(decoded).toString('base64url') !== token) return invalid();
+    const parts = decoded.split('.');
+    const [version, unsubscribeId = '', campaignId = '', signature = ''] = parts;
+    if (
+        parts.length !== 4 ||
+        version !== 'v2' ||
+        !recipientIdPattern.test(unsubscribeId) ||
+        !/^[a-z0-9-]{3,64}$/.test(campaignId) ||
+        !/^[A-Za-z0-9_-]{43}$/.test(signature)
+    )
+        return invalid();
+    const expected = signCampaignUnsubscribeToken(unsubscribeId, campaignId);
+    const a = Buffer.from(token),
+        b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b)) return invalid();
+    return { unsubscribeId, campaignId };
+};
+
+/** No campaign lookup: old links remain valid after campaign archive/deletion. */
+export const unsubscribeFromCampaignEmails = async (token: string): Promise<boolean> => {
+    const { unsubscribeId } = verifyCampaignUnsubscribeToken(token);
+    await unsubscribeCampaignRecipient(unsubscribeId);
+    return true;
+};

package/src/helpers/campaign-webhook.helpers.test.ts

@@ -0,0 +1,137 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Campaign, LCNNotification } from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({
+    fetch: vi.fn(),
+    acknowledge: vi.fn(),
+    getCampaign: vi.fn(),
+    recipient: vi.fn(),
+    environment: {
+        NODE_ENV: 'test',
+        IS_OFFLINE: false,
+        DOMAIN_NAME: 'brain.example',
+        NOTIFICATIONS_SERVICE_WEBHOOK_URL: 'https://inbox.example/notifications',
+    },
+}));
+
+vi.mock('./notification-webhook-fetch.helpers', () => ({
+    fetchNotificationWebhook: (...args: unknown[]) => mocks.fetch(...args),
+}));
+
+vi.mock('@environment', () => ({
+    environment: mocks.environment,
+    getNotificationRuntimeEnvironment: () => mocks.environment,
+}));
+vi.mock('@helpers/learnCard.helpers', () => ({
+    getDidWebLearnCard: async () => ({
+        id: { did: () => 'did:web:brain.example' },
+        invoke: { getDidAuthVp: async () => 'test-jwt' },
+    }),
+}));
+vi.mock('@helpers/did.helpers', () => ({
+    getDidWeb: (domain: string, profileId: string) => `did:web:${domain}:users:${profileId}`,
+}));
+vi.mock('@accesslayer/inbox-credential/relationships/create', () => ({
+    createWebhookSentRelationship: vi.fn(),
+}));
+vi.mock('@cache', () => ({ default: {} }));
+// These suites exercise notification delivery without email transport or a database.
+vi.mock('@helpers/campaign-email.helpers', () => ({ sendCampaignEmail: vi.fn() }));
+vi.mock('@accesslayer/campaign/preferences', () => ({
+    getAnnouncementPreferences: async () => ({
+        announcementEmailOptOut: false,
+        announcementPushOptOut: false,
+    }),
+}));
+vi.mock('@accesslayer/campaign/read', () => ({ getCampaign: mocks.getCampaign }));
+vi.mock('@accesslayer/campaign/test', () => ({ queueCampaignInAppTest: vi.fn() }));
+vi.mock('@accesslayer/campaign/delivery', () => ({
+    getCampaignDeliveryRecipient: mocks.recipient,
+    acknowledgeCampaignNotification: mocks.acknowledge,
+}));
+vi.mock('@helpers/contract-events.helpers', () => ({
+    authorizeContractNotification: async () => true,
+}));
+vi.mock('@helpers/connectionPrompt.helpers', () => ({
+    acknowledgeConnectionPromptNotificationDelivery: vi.fn(),
+}));
+
+import { buildCampaignNotification } from './campaign-notifications.helpers';
+import { deliverQueuedNotification } from './notificationQueue.helpers';
+
+const campaign = {
+    id: 'webhook-pilot',
+    createdAt: '2026-01-01T00:00:00Z',
+    status: 'live',
+    channels: ['notify'],
+    notification: { title: 'Explore', body: 'Find your next step' },
+} as Campaign;
+const recipient = {
+    profileId: 'learner',
+    did: 'did:web:brain.example:users:learner',
+    notificationsWebhook: 'https://receiver.example/notifications',
+};
+
+beforeEach(() => {
+    vi.resetAllMocks();
+    mocks.environment.NOTIFICATIONS_SERVICE_WEBHOOK_URL = 'https://inbox.example/notifications';
+    mocks.getCampaign.mockResolvedValue(campaign);
+    mocks.recipient.mockResolvedValue(recipient);
+});
+
+describe('campaign custom webhook storage contract', () => {
+    it.each([
+        true,
+        { sent: true },
+        { success: true },
+        { ok: true },
+        { data: { success: true } },
+        { result: { data: { sent: true } } },
+    ])('acknowledges recognized durable storage response %j', async response => {
+        mocks.fetch.mockResolvedValue(new Response(JSON.stringify(response)));
+        const notification = await buildCampaignNotification(campaign, recipient);
+
+        await deliverQueuedNotification(JSON.stringify(notification));
+
+        expect(mocks.fetch).toHaveBeenCalledWith(
+            recipient.notificationsWebhook,
+            expect.objectContaining({ method: 'POST' }),
+            false
+        );
+        expect(mocks.acknowledge).toHaveBeenCalledOnce();
+        expect(mocks.acknowledge).toHaveBeenCalledWith(
+            expect.objectContaining({
+                data: notification.data,
+            })
+        );
+    });
+
+    it.each([
+        { status: 204, body: null },
+        { status: 200, body: '' },
+        { status: 202, body: 'accepted' },
+        { status: 200, body: '{"status":"ok"}' },
+        { status: 200, body: '{"sent":false}' },
+        { status: 200, body: '{"success":false}' },
+        { status: 200, body: '{"ok":false}' },
+    ])('retries without counting storage for $status / $body', async ({ status, body }) => {
+        mocks.fetch.mockResolvedValueOnce(new Response(body, { status }));
+        const notification = await buildCampaignNotification(campaign, recipient);
+        const queuedBody = JSON.stringify(notification);
+
+        await expect(deliverQueuedNotification(queuedBody)).rejects.toThrow();
+        expect(mocks.acknowledge).not.toHaveBeenCalled();
+
+        mocks.fetch.mockResolvedValueOnce(new Response('{"sent":true}'));
+        await deliverQueuedNotification(queuedBody);
+        expect(mocks.fetch).toHaveBeenCalledTimes(2);
+        expect(mocks.acknowledge).toHaveBeenCalledOnce();
+        const attempts = mocks.fetch.mock.calls.map(
+            ([, request]) => JSON.parse(request.body) as LCNNotification
+        );
+        // A receiver can deduplicate even if its first storage acknowledgement was lost.
+        expect(attempts[1]!.data?.metadata).toEqual(attempts[0]!.data?.metadata);
+        expect(attempts[1]!.to.did).toBe(attempts[0]!.to.did);
+        expect(attempts[1]!.from).toEqual(attempts[0]!.from);
+    });
+});

package/src/helpers/consentflow-deadline.helpers.ts

@@ -0,0 +1,22 @@
+import { neogma } from '@instance';
+
+export type ConsentFlowDeadlineSummary = { suspended: number };
+
+/** Move expired pending re-consents to suspended; safe to run repeatedly. */
+export const suspendExpiredConsentFlowTerms = async (
+    now = new Date().toISOString()
+): Promise<ConsentFlowDeadlineSummary> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (terms:ConsentFlowTerms)
+         WHERE terms.status = 'needs_reconsent'
+           AND terms.reconsentDeadline IS NOT NULL
+           AND terms.reconsentDeadline <= $now
+         SET terms.status = 'suspended', terms.updatedAt = $now
+         RETURN count(terms) AS suspended`,
+        { now }
+    );
+    const value = result.records[0]?.get('suspended');
+    return {
+        suspended: typeof value?.toNumber === 'function' ? value.toNumber() : Number(value ?? 0),
+    };
+};

package/src/helpers/consentflow-legacy-migration.helpers.ts

@@ -0,0 +1,179 @@
+import { neogma } from '@instance';
+import { inflateObject } from '@helpers/objects.helpers';
+import { v4 as uuid } from 'uuid';
+import { ConsentFlowContractValidator } from '@learncard/types';
+import type { ConsentFlowContract } from '@learncard/types';
+
+/** Recovers explicit review baselines without mistaking quiet publications or syncs for approval. */
+const backfillConsentReviewBaselines = async (): Promise<void> => {
+    const marker = await neogma.queryRunner.run(`
+        MATCH (migration:ConsentFlowContractMigration {id:'holder-review-v1'})
+        WHERE migration.completedAt IS NOT NULL
+        RETURN migration.completedAt AS completedAt
+    `);
+    if (marker.records.length) return;
+    await neogma.queryRunner.run(`
+        MERGE (migration:ConsentFlowContractMigration {id:'holder-review-v1'})
+        SET migration._reviewLock=coalesce(migration._reviewLock,0)+1
+        WITH migration
+        CALL {
+            WITH migration
+            MATCH (terms:ConsentFlowTerms)-[:CONSENTS_TO]->(contract:ConsentFlowContract)
+            WHERE migration.completedAt IS NULL AND terms.lastReviewedVersion IS NULL
+            OPTIONAL MATCH (transaction:ConsentFlowTransaction)-[:IS_FOR]->(terms)
+            WHERE transaction.action IN ['consent','reconsent']
+                OR (transaction.action='update' AND transaction.status IS NOT NULL)
+            WITH terms, contract, max(transaction.date) AS reviewedAt
+            OPTIONAL MATCH (contract)-[:HAS_VERSION]->(version:ConsentFlowContractVersion)
+            WHERE version.version <= coalesce(terms.consentedVersion,1)
+                AND version.createdAt <= coalesce(reviewedAt,terms.createdAt,version.createdAt)
+            WITH terms, max(version.version) AS reviewedVersion
+            SET terms.lastReviewedVersion=coalesce(terms.lastReviewedVersion,reviewedVersion,1)
+            RETURN count(terms) AS initialized
+        }
+        SET migration.completedAt=coalesce(migration.completedAt,toString(datetime()))
+        REMOVE migration._reviewLock
+        RETURN initialized
+    `);
+};
+
+/** Backfills v1 snapshots and legacy consent markers idempotently. */
+export const migrateLegacyConsentFlowContracts = async (contractId?: string): Promise<void> => {
+    const scoped = contractId !== undefined;
+    if (!scoped) {
+        const marker = await neogma.queryRunner.run(
+            `MATCH (migration:ConsentFlowContractMigration {id:'legacy-v1'})
+             WHERE migration.completedAt IS NOT NULL
+             RETURN migration.completedAt AS completedAt`
+        );
+        if (marker.records.length > 0) {
+            await backfillConsentReviewBaselines();
+            return;
+        }
+    }
+    const legacy = await neogma.queryRunner.run(
+        `
+        MATCH (contract:ConsentFlowContract)
+        WHERE ($contractId IS NULL OR contract.id=$contractId)
+          AND contract.currentVersion IS NULL
+          AND NOT EXISTS { MATCH (contract)-[:HAS_VERSION]->(:ConsentFlowContractVersion) }
+        OPTIONAL MATCH (contract)-[autoReceive:AUTO_RECEIVE]->(boost:Boost)
+        WITH contract, collect(CASE WHEN boost IS NULL THEN null ELSE {
+            id: boost.id, signingAuthorityEndpoint: coalesce(autoReceive.signingAuthorityEndpoint, 'default'),
+            signingAuthorityName: coalesce(autoReceive.signingAuthorityName, 'default'), issuer: autoReceive.issuer
+        } END) AS rawAutoboosts
+        OPTIONAL MATCH (contract)-[:CAN_WRITE]->(writer:Profile)
+        WITH contract, rawAutoboosts, collect(DISTINCT writer.profileId) AS writers
+        RETURN properties(contract) AS properties,
+               [config IN rawAutoboosts WHERE config IS NOT NULL] AS autoboosts,
+               writers
+    `,
+        { contractId: contractId ?? null }
+    );
+    if (scoped && !legacy.records.length) return;
+    let skippedCount = 0;
+    const skipped: { contractId: string; reason: string }[] = [];
+    for (const record of legacy.records) {
+        const properties = record.get('properties') as Record<string, unknown>;
+        const contractProps = Object.fromEntries(
+            Object.entries(properties)
+                .filter(([key]) => key.startsWith('contract.'))
+                .map(([key, value]) => [key.slice('contract.'.length), value])
+        );
+        let contract: ConsentFlowContract;
+        try {
+            contract = ConsentFlowContractValidator.parse(
+                inflateObject<Record<string, unknown>>(contractProps)
+            );
+        } catch {
+            skippedCount += 1;
+            if (skipped.length < 25)
+                skipped.push({ contractId: String(properties.id), reason: 'invalid_contract' });
+            continue;
+        }
+        const autoboosts = record.get('autoboosts') as StoredAutoBoost[];
+        const writers = (record.get('writers') as (string | null)[]).filter(
+            (writer): writer is string => !!writer
+        );
+        await neogma.queryRunner.run(
+            `MATCH (contract:ConsentFlowContract {id:$id})
+             WHERE contract.currentVersion IS NULL
+               AND NOT EXISTS { MATCH (contract)-[:HAS_VERSION]->(:ConsentFlowContractVersion) }
+             SET contract._legacyMigrationLock = true
+             REMOVE contract._legacyMigrationLock
+             WITH contract
+             WHERE contract.currentVersion IS NULL
+               AND NOT EXISTS { MATCH (contract)-[:HAS_VERSION]->(:ConsentFlowContractVersion) }
+             CREATE (version:ConsentFlowContractVersion {
+                 id:$versionId, version:1, contract:$contractSnapshot, name:$name,
+                 subtitle:$subtitle, description:$description, reasonForAccessing:$reasonForAccessing,
+                 image:$image, needsGuardianConsent:$needsGuardianConsent, redirectUrl:$redirectUrl,
+                 frontDoorBoostUri:$frontDoorBoostUri, expiresAt:$expiresAt,
+                 autoboosts:$autoboostSnapshot, writers:$writerSnapshot, createdAt:$createdAt
+             })
+             CREATE (contract)-[:HAS_VERSION]->(version)
+             SET contract.currentVersion=1
+             WITH contract
+             MATCH (terms:ConsentFlowTerms)-[:CONSENTS_TO]->(contract)
+             SET terms.consentedVersion=coalesce(terms.consentedVersion,1),
+                 terms.lastReviewedVersion=coalesce(terms.lastReviewedVersion,terms.consentedVersion,1),
+                 terms.status=CASE WHEN terms.status='stale' THEN 'consumed' ELSE terms.status END`,
+            {
+                id: String(properties.id),
+                versionId: uuid(),
+                contractSnapshot: JSON.stringify(contract),
+                autoboostSnapshot: JSON.stringify(autoboosts),
+                writerSnapshot: JSON.stringify(writers),
+                createdAt: String(
+                    properties.updatedAt ?? properties.createdAt ?? new Date().toISOString()
+                ),
+                name: properties.name,
+                subtitle: properties.subtitle ?? null,
+                description: properties.description ?? null,
+                reasonForAccessing: properties.reasonForAccessing ?? null,
+                image: properties.image ?? null,
+                needsGuardianConsent: properties.needsGuardianConsent ?? false,
+                redirectUrl: properties.redirectUrl ?? null,
+                frontDoorBoostUri: properties.frontDoorBoostUri ?? null,
+                expiresAt: properties.expiresAt ?? null,
+            }
+        );
+    }
+    if (!scoped) {
+        await neogma.queryRunner.run(`
+            MATCH (contract:ConsentFlowContract)-[:HAS_VERSION]->(:ConsentFlowContractVersion {version:1})
+            WHERE contract.currentVersion IS NULL
+            SET contract.currentVersion=1
+        `);
+        await neogma.queryRunner.run(`
+            MATCH (terms:ConsentFlowTerms)-[:CONSENTS_TO]->(:ConsentFlowContract)
+            WHERE terms.consentedVersion IS NULL
+            SET terms.consentedVersion=1
+        `);
+        await neogma.queryRunner.run(`
+            MATCH (terms:ConsentFlowTerms)
+            WHERE terms.status='stale'
+            SET terms.status='consumed'
+        `);
+        await backfillConsentReviewBaselines();
+    }
+    if (skippedCount) {
+        console.warn('Skipped malformed legacy ConsentFlow contracts', {
+            count: skippedCount,
+            contracts: skipped,
+            truncated: skippedCount > skipped.length,
+        });
+        return;
+    }
+    if (scoped) return;
+    await neogma.queryRunner.run(`
+        MERGE (migration:ConsentFlowContractMigration {id:'legacy-v1'})
+        SET migration.completedAt=coalesce(migration.completedAt, toString(datetime()))
+    `);
+};
+type StoredAutoBoost = {
+    id: string;
+    signingAuthorityEndpoint?: string;
+    signingAuthorityName?: string;
+    issuer?: string;
+};