@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/accesslayer/consentflowcontract/versions.ts

@@ -0,0 +1,790 @@
+import { isDeepStrictEqual } from 'node:util';
+import { getIdFromUri } from '@helpers/uri.helpers';
+import { flattenObject } from '@helpers/objects.helpers';
+import {
+    classifyContractChange,
+    diffContractChange,
+    buildContractUpdatePreview,
+} from '@learncard/helpers';
+import {
+    ConsentFlowContractValidator,
+    ConsentFlowContractChangeKindValidator,
+} from '@learncard/types';
+import type {
+    ConsentFlowContract as ConsentFlowContractType,
+    ConsentFlowContractChangeKind,
+    ConsentFlowContractUpdateResult,
+    ConsentFlowContractChanges,
+    ConsentFlowContractDetails,
+    ConsentFlowTermsStatus,
+    ConsentFlowContractDiff,
+} from '@learncard/types';
+import { z } from 'zod';
+import { migrateLegacyConsentFlowContracts } from '@helpers/consentflow-legacy-migration.helpers';
+import { neogma } from '@instance';
+import { TRPCError } from '@trpc/server';
+import { v4 as uuid } from 'uuid';
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { getSigningAuthorityForUserByName } from '@accesslayer/signing-authority/relationships/read';
+import { getBoostById } from '@accesslayer/boost/read';
+import { canProfileIssueBoost } from '@accesslayer/boost/relationships/read';
+import { tryDispatchContractEvent } from '@helpers/contract-events.helpers';
+
+export type StoredContractVersion = {
+    id: string;
+    version: number;
+    createdAt: string;
+    reason?: string;
+    kind?: ConsentFlowContractChangeKind;
+    contract: ConsentFlowContractType;
+    name: string;
+    subtitle?: string;
+    description?: string;
+    reasonForAccessing?: string;
+    image?: string;
+    needsGuardianConsent?: boolean;
+    redirectUrl?: string;
+    frontDoorBoostUri?: string;
+    expiresAt?: string;
+    autoboosts: {
+        id: string;
+        signingAuthorityEndpoint: string;
+        signingAuthorityName: string;
+        issuer?: string;
+    }[];
+    writers: string[];
+};
+
+const StoredAutoBoostValidator = z.object({
+    id: z.string(),
+    signingAuthorityEndpoint: z.string(),
+    signingAuthorityName: z.string(),
+    issuer: z
+        .string()
+        .nullable()
+        .optional()
+        .transform(value => value ?? undefined),
+});
+
+const parseJson = <T>(value: unknown, validator: z.ZodType<T>, field: string): T => {
+    try {
+        const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+        return validator.parse(parsed);
+    } catch {
+        throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: `Stored contract version has invalid ${field}`,
+        });
+    }
+};
+
+const parseVersion = (raw: Record<string, unknown>): StoredContractVersion =>
+    ({
+        ...raw,
+        version: Number(raw.version),
+        contract: parseJson(raw.contract, ConsentFlowContractValidator, 'contract'),
+        autoboosts: parseJson(raw.autoboosts, z.array(StoredAutoBoostValidator), 'autoboosts'),
+        writers: parseJson(raw.writers, z.array(z.string()), 'writers'),
+        ...(raw.kind ? { kind: ConsentFlowContractChangeKindValidator.parse(raw.kind) } : {}),
+    }) as StoredContractVersion;
+
+const mergeScopePatch = (
+    current: ConsentFlowContractType['read']['personal'],
+    patch?: Record<string, ConsentFlowContractType['read']['personal'][string] | null>
+) => {
+    if (!patch) return current;
+    const merged = { ...current };
+    for (const [key, config] of Object.entries(patch)) {
+        if (config === null) delete merged[key];
+        else merged[key] = { ...current[key], ...config };
+    }
+    return merged;
+};
+
+const mergeConsentFlowContractPatch = (
+    current: ConsentFlowContractType,
+    patch: ConsentFlowContractChanges['contract']
+): ConsentFlowContractType => {
+    const read = patch?.read
+        ? {
+              ...current.read,
+              ...patch.read,
+              credentials: patch.read.credentials
+                  ? {
+                        ...current.read.credentials,
+                        ...patch.read.credentials,
+                        categories: mergeScopePatch(
+                            current.read.credentials.categories,
+                            patch.read.credentials.categories
+                        ),
+                    }
+                  : current.read.credentials,
+              personal: mergeScopePatch(current.read.personal, patch.read.personal),
+          }
+        : current.read;
+    const write = patch?.write
+        ? {
+              ...current.write,
+              ...patch.write,
+              credentials: patch.write.credentials
+                  ? {
+                        ...current.write.credentials,
+                        ...patch.write.credentials,
+                        categories: mergeScopePatch(
+                            current.write.credentials.categories,
+                            patch.write.credentials.categories
+                        ),
+                    }
+                  : current.write.credentials,
+              personal: mergeScopePatch(current.write.personal, patch.write.personal),
+          }
+        : current.write;
+    return ConsentFlowContractValidator.parse({ ...current, read, write });
+};
+export const getConsentFlowContractVersionRecord = async (
+    contractId: string,
+    versionNumber: number
+): Promise<StoredContractVersion | null> => {
+    let result = await neogma.queryRunner.run(
+        `MATCH (:ConsentFlowContract {id:$contractId})-[:HAS_VERSION]->(v:ConsentFlowContractVersion {version:$version})
+         RETURN properties(v) AS version LIMIT 1`,
+        { contractId, version: versionNumber }
+    );
+    if (!result.records.length && versionNumber === 1) {
+        await migrateLegacyConsentFlowContracts(contractId);
+        result = await neogma.queryRunner.run(
+            `MATCH (:ConsentFlowContract {id:$contractId})-[:HAS_VERSION]->(v:ConsentFlowContractVersion {version:$version})
+                 RETURN properties(v) AS version LIMIT 1`,
+            { contractId, version: versionNumber }
+        );
+    }
+    const raw = result.records[0]?.get('version') as Record<string, unknown> | undefined;
+    return raw ? parseVersion(raw) : null;
+};
+
+/** Loads accepted snapshots in one query per bounded page, not per consenter. */
+export const getConsentFlowContractVersionRecords = async (
+    requests: { contractId: string; version: number }[]
+): Promise<Map<string, StoredContractVersion>> => {
+    const unique = new Map(
+        requests.map(request => [`${request.contractId}:${request.version}`, request])
+    );
+    const versions = new Map<string, StoredContractVersion>();
+    if (!unique.size) return versions;
+    const result = await neogma.queryRunner.run(
+        `UNWIND $requests AS request
+         MATCH (:ConsentFlowContract {id:request.contractId})-[:HAS_VERSION]->(v:ConsentFlowContractVersion {version:request.version})
+         RETURN request.contractId AS contractId, properties(v) AS version`,
+        { requests: [...unique.values()] }
+    );
+    for (const record of result.records) {
+        const version = parseVersion(record.get('version') as Record<string, unknown>);
+        versions.set(`${record.get('contractId')}:${version.version}`, version);
+    }
+    return versions;
+};
+
+export const getConsentFlowContractVersion = getConsentFlowContractVersionRecord;
+
+export const getConsentFlowContractVersions = async (uri: string) => {
+    const contractId = getIdFromUri(uri);
+    const result = await neogma.queryRunner.run(
+        `MATCH (c:ConsentFlowContract {id:$contractId})-[:HAS_VERSION]->(v:ConsentFlowContractVersion)
+         RETURN properties(v) AS version ORDER BY v.version DESC`,
+        { contractId }
+    );
+    return result.records.map(record =>
+        parseVersion(record.get('version') as Record<string, unknown>)
+    );
+};
+
+export const getContractVersions = getConsentFlowContractVersions;
+type CumulativeContractUpdateRequest = {
+    key: string;
+    contractId: string;
+    acceptedVersion: number;
+    status?: ConsentFlowTermsStatus;
+    reconsentDeadline?: string;
+};
+
+/** Fetches each accepted/current pair once while retaining per-holder status and deadline. */
+export const getCumulativeContractUpdates = async (
+    requests: CumulativeContractUpdateRequest[]
+): Promise<Map<string, NonNullable<ConsentFlowContractDetails['latestUpdate']>>> => {
+    const updates = new Map<string, NonNullable<ConsentFlowContractDetails['latestUpdate']>>();
+    if (!requests.length) return updates;
+    const pairs = new Map(
+        requests.map(request => [
+            `${request.contractId}:${request.acceptedVersion}`,
+            {
+                key: `${request.contractId}:${request.acceptedVersion}`,
+                contractId: request.contractId,
+                acceptedVersion: request.acceptedVersion,
+            },
+        ])
+    );
+    const result = await neogma.queryRunner.run(
+        `UNWIND $requests AS request
+         OPTIONAL MATCH (c:ConsentFlowContract {id:request.contractId})
+         OPTIONAL MATCH (c)-[:HAS_VERSION]->(accepted:ConsentFlowContractVersion {version:request.acceptedVersion})
+         OPTIONAL MATCH (c)-[:HAS_VERSION]->(current:ConsentFlowContractVersion {version:c.currentVersion})
+         OPTIONAL MATCH (c)-[:HAS_VERSION]->(intermediate:ConsentFlowContractVersion)
+         WHERE intermediate.version > request.acceptedVersion
+             AND intermediate.version <= c.currentVersion AND intermediate.kind='requires_consent'
+         WITH request, c, accepted, current, intermediate ORDER BY intermediate.version ASC
+         RETURN request.key AS key, c.id AS contractId, c.currentVersion AS currentVersion,
+             c.latestUpdate AS latestUpdate, properties(accepted) AS accepted, properties(current) AS current,
+             head(collect(CASE WHEN intermediate IS NULL THEN null ELSE {reason:intermediate.reason} END)) AS firstRequired`,
+        { requests: [...pairs.values()] }
+    );
+    const rows = new Map(result.records.map(record => [String(record.get('key')), record]));
+    const parsedPairs = new Map<
+        string,
+        {
+            current: StoredContractVersion;
+            diff: ConsentFlowContractDiff;
+            kind: ConsentFlowContractChangeKind;
+            reason?: string;
+            requiredReason?: string;
+            deadline?: string;
+        }
+    >();
+    for (const request of requests) {
+        const key = `${request.contractId}:${request.acceptedVersion}`;
+        const record = rows.get(key);
+        if (!record?.get('contractId'))
+            throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
+        if (request.acceptedVersion >= Number(record.get('currentVersion') ?? 1)) continue;
+        let pair = parsedPairs.get(key);
+        if (!pair) {
+            if (!record.get('accepted') || !record.get('current'))
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: 'Contract version snapshot is missing',
+                });
+            const accepted = parseVersion(record.get('accepted') as Record<string, unknown>);
+            const current = parseVersion(record.get('current') as Record<string, unknown>);
+            const latest = record.get('latestUpdate')
+                ? parseJson(
+                      record.get('latestUpdate'),
+                      z.object({
+                          reason: z.string().optional(),
+                          reconsentDeadline: z.string().optional(),
+                      }),
+                      'latest update'
+                  )
+                : undefined;
+            const firstRequired = record.get('firstRequired') as { reason?: string } | null;
+            pair = {
+                current,
+                diff: diffContractChange(accepted, current),
+                kind: classifyContractChange(accepted, current),
+                reason: latest?.reason,
+                requiredReason: firstRequired?.reason ?? latest?.reason,
+                deadline: latest?.reconsentDeadline,
+            };
+            parsedPairs.set(key, pair);
+        }
+        const requiresApproval =
+            request.status === 'needs_reconsent' || request.status === 'suspended';
+        const kind = requiresApproval ? 'requires_consent' : pair.kind;
+        const reason = requiresApproval ? pair.requiredReason : pair.reason;
+        const deadline = requiresApproval
+            ? (request.reconsentDeadline ?? pair.deadline)
+            : undefined;
+        updates.set(request.key, {
+            fromVersion: request.acceptedVersion,
+            toVersion: pair.current.version,
+            kind,
+            ...(reason ? { reason } : {}),
+            diff: pair.diff,
+            ...(deadline ? { reconsentDeadline: deadline } : {}),
+            createdAt: pair.current.createdAt,
+            preview: buildContractUpdatePreview({
+                name: pair.current.name,
+                kind,
+                diff: pair.diff,
+                status: request.status,
+            }),
+        });
+    }
+    return updates;
+};
+
+export const getCumulativeContractUpdateById = async (
+    contractId: string,
+    acceptedVersion: number,
+    status?: ConsentFlowTermsStatus,
+    reconsentDeadline?: string
+): Promise<ConsentFlowContractDetails['latestUpdate']> =>
+    (
+        await getCumulativeContractUpdates([
+            { key: contractId, contractId, acceptedVersion, status, reconsentDeadline },
+        ])
+    ).get(contractId);
+
+export const getCumulativeContractUpdate = async (
+    uri: string,
+    acceptedVersion: number,
+    status?: ConsentFlowTermsStatus,
+    reconsentDeadline?: string
+): Promise<ConsentFlowContractDetails['latestUpdate']> =>
+    getCumulativeContractUpdateById(getIdFromUri(uri), acceptedVersion, status, reconsentDeadline);
+
+type ContractChanges = {
+    contract?: ConsentFlowContractChanges['contract'];
+    name?: string;
+    subtitle?: string;
+    description?: string;
+    reasonForAccessing?: string;
+    image?: string;
+    needsGuardianConsent?: boolean;
+    redirectUrl?: string;
+    frontDoorBoostUri?: string;
+    expiresAt?: string | null;
+    autoboosts?: Omit<StoredContractVersion['autoboosts'][number], 'issuer'>[];
+    writers?: string[];
+    recipients?: string[];
+};
+
+export const updateConsentFlowContractVersion = async (
+    {
+        uri,
+        changes,
+        reason,
+        reconsentDeadline,
+        dryRun,
+        expectedVersion,
+    }: {
+        uri: string;
+        changes: ContractChanges;
+        reason?: string;
+        reconsentDeadline?: string;
+        dryRun?: boolean;
+        expectedVersion?: number;
+    },
+    actorProfileId: string,
+    domain: string,
+    appBaseUrl?: string
+): Promise<ConsentFlowContractUpdateResult> => {
+    const contractId = getIdFromUri(uri);
+    const storedResult = await neogma.queryRunner.run(
+        `MATCH (c:ConsentFlowContract {id:$id})
+         RETURN properties(c) AS contract, c.status AS contractStatus, c.currentVersion AS currentVersion,
+         [(c)-[r:AUTO_RECEIVE]->(b:Boost) | {id:b.id,signingAuthorityEndpoint:r.signingAuthorityEndpoint,signingAuthorityName:r.signingAuthorityName,issuer:r.issuer}] AS autoBoosts,
+         [(c)-[:CREATED_BY]->(owner:Profile) | owner.profileId][0] AS ownerProfileId,
+         EXISTS { MATCH (c)-[:CREATED_BY]->(:Profile {profileId:$actor}) } AS owner,
+         EXISTS { MATCH (c)-[:CAN_WRITE]->(:Profile {profileId:$actor}) } AS writer`,
+        { id: contractId, actor: actorProfileId }
+    );
+    const stored = storedResult.records[0];
+    if (!stored) throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
+    if (!stored.get('owner')) {
+        throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: 'Only the contract owner can update it',
+        });
+    }
+    if (stored.get('contractStatus') === 'retired') {
+        throw new TRPCError({ code: 'FORBIDDEN', message: 'Retired contracts cannot be updated' });
+    }
+    if (changes.recipients !== undefined) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Use addContractRecipient or removeContractRecipient to update recipients',
+        });
+    }
+    const currentVersion = Number(stored.get('currentVersion') ?? 1);
+    if (expectedVersion !== undefined && expectedVersion !== currentVersion) {
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'Contract changed since this draft was opened; reload before publishing',
+        });
+    }
+    const current = await getConsentFlowContractVersionRecord(contractId, currentVersion);
+    if (!current)
+        throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: 'Contract version snapshot is missing',
+        });
+    const existingAutoBoosts =
+        (stored.get('autoBoosts') as StoredContractVersion['autoboosts'] | null) ?? [];
+    const requestedAutoBoosts = changes.autoboosts ?? current.autoboosts;
+    const uniqueAutoBoosts = new Map<string, (typeof requestedAutoBoosts)[number]>();
+    for (const config of requestedAutoBoosts) {
+        const previous = uniqueAutoBoosts.get(config.id);
+        if (
+            previous &&
+            (previous.signingAuthorityEndpoint !== config.signingAuthorityEndpoint ||
+                previous.signingAuthorityName !== config.signingAuthorityName)
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: `Conflicting signing authorities for autoboost: ${config.id}`,
+            });
+        }
+        uniqueAutoBoosts.set(config.id, config);
+    }
+    const requestedWriterIds = [...new Set(changes.writers ?? current.writers)];
+    const targets = await neogma.queryRunner.run(
+        `OPTIONAL MATCH (boost:Boost) WHERE boost.id IN $boostIds
+         WITH collect(DISTINCT boost.id) AS boostIds
+         OPTIONAL MATCH (writer:Profile) WHERE writer.profileId IN $writerIds
+         RETURN boostIds, collect(DISTINCT writer.profileId) AS writerIds`,
+        { boostIds: [...uniqueAutoBoosts.keys()], writerIds: requestedWriterIds }
+    );
+    const existingBoostIds = new Set((targets.records[0]?.get('boostIds') as string[]) ?? []);
+    const existingWriterIds = new Set((targets.records[0]?.get('writerIds') as string[]) ?? []);
+    const missingBoost = [...uniqueAutoBoosts.keys()].find(id => !existingBoostIds.has(id));
+    const missingWriter = requestedWriterIds.find(id => !existingWriterIds.has(id));
+    if (missingBoost || missingWriter) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: missingBoost
+                ? `Unknown AutoBoost: ${missingBoost}`
+                : `Unknown writer: ${missingWriter}`,
+        });
+    }
+    const autoboosts = await Promise.all(
+        [...uniqueAutoBoosts.values()].map(async config => {
+            const existing = existingAutoBoosts.find(item => item.id === config.id);
+            const unchanged =
+                existing &&
+                existing.signingAuthorityEndpoint === config.signingAuthorityEndpoint &&
+                existing.signingAuthorityName === config.signingAuthorityName;
+            if (existing?.issuer && existing.issuer !== actorProfileId && !unchanged) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message:
+                        'Existing delegated delivery cannot change signers; remove it before configuring owner delivery',
+                });
+            }
+            const issuer = unchanged ? (existing.issuer ?? actorProfileId) : actorProfileId;
+            if (!unchanged) {
+                const issuerProfile = await getProfileByProfileId(issuer);
+                const boost = await getBoostById(config.id);
+                if (
+                    !issuerProfile ||
+                    !boost ||
+                    !(await canProfileIssueBoost(issuerProfile, boost))
+                ) {
+                    throw new TRPCError({
+                        code: 'UNAUTHORIZED',
+                        message: 'The contract owner cannot issue this AutoBoost',
+                    });
+                }
+                const signingAuthority =
+                    issuerProfile &&
+                    (await getSigningAuthorityForUserByName(
+                        issuerProfile,
+                        config.signingAuthorityEndpoint,
+                        config.signingAuthorityName.toLowerCase()
+                    ));
+                if (!signingAuthority) {
+                    throw new TRPCError({
+                        code: 'FORBIDDEN',
+                        message: `Signing authority ${config.signingAuthorityName} is not registered for autoboost issuer ${issuer}`,
+                    });
+                }
+            }
+            return {
+                id: config.id,
+                signingAuthorityEndpoint: config.signingAuthorityEndpoint,
+                signingAuthorityName: config.signingAuthorityName,
+                issuer,
+            };
+        })
+    );
+    const next: StoredContractVersion = {
+        ...current,
+        ...Object.fromEntries(
+            Object.entries(changes).filter(
+                ([key, value]) =>
+                    key !== 'contract' &&
+                    key !== 'recipients' &&
+                    key !== 'expiresAt' &&
+                    value !== undefined
+            )
+        ),
+        contract: changes.contract
+            ? mergeConsentFlowContractPatch(current.contract, changes.contract)
+            : current.contract,
+        expiresAt:
+            changes.expiresAt === null ? undefined : (changes.expiresAt ?? current.expiresAt),
+        autoboosts,
+        writers: changes.writers ?? current.writers,
+    };
+    const kind = classifyContractChange(current, next);
+    const diff = diffContractChange(current, next);
+    if (reason && reason.length > 140) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Reason must be at most 140 characters',
+        });
+    }
+    if (kind === 'requires_consent' && !reason) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'A reason is required when asking users for more access',
+        });
+    }
+    if (next.expiresAt && !z.iso.datetime().safeParse(next.expiresAt).success) {
+        throw new TRPCError({ code: 'BAD_REQUEST', message: 'expiresAt must be a valid ISO date' });
+    }
+    if (
+        reconsentDeadline &&
+        (!z.iso.datetime().safeParse(reconsentDeadline).success ||
+            Date.parse(reconsentDeadline) <= Date.now())
+    ) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'reconsentDeadline must be a future ISO date',
+        });
+    }
+    const effectiveDeadline =
+        kind === 'requires_consent'
+            ? (reconsentDeadline ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString())
+            : undefined;
+    const preview = buildContractUpdatePreview({ name: next.name, kind, diff });
+    const reviewUrl = `${(appBaseUrl ?? domain).replace(/\/+$/, '')}/consent-flow/review?uri=${encodeURIComponent(uri)}`;
+    const contractOwnerProfileId = stored.get('ownerProfileId');
+    if (typeof contractOwnerProfileId !== 'string') {
+        throw new TRPCError({ code: 'PRECONDITION_FAILED', message: 'Contract owner is missing' });
+    }
+    const currentAutoBoosts = new Map(current.autoboosts.map(config => [config.id, config]));
+    const autoBoostsUnchanged =
+        autoboosts.length === currentAutoBoosts.size &&
+        autoboosts.every(config => {
+            const previous = currentAutoBoosts.get(config.id);
+            return (
+                previous?.signingAuthorityEndpoint === config.signingAuthorityEndpoint &&
+                previous.signingAuthorityName === config.signingAuthorityName &&
+                (previous.issuer ?? contractOwnerProfileId) === config.issuer
+            );
+        });
+    if (
+        isDeepStrictEqual(current.contract, next.contract) &&
+        !diff.details?.length &&
+        autoBoostsUnchanged
+    ) {
+        return { version: currentVersion, kind, affectedUsers: 0, preview };
+    }
+    const affectedUsers = await neogma.queryRunner
+        .run(
+            `MATCH (profile:Profile)-[:CREATED_BY]->(t:ConsentFlowTerms)-[:CONSENTS_TO]->(c:ConsentFlowContract {id:$id})
+         WHERE t.status IN ['live','needs_reconsent','suspended'] RETURN count(DISTINCT profile.profileId) AS count`,
+            { id: contractId }
+        )
+        .then(r => Number(r.records[0]?.get('count') ?? 0));
+    const eventId = `${contractId}:version:${currentVersion + 1}`;
+    const notificationData = {
+        contractUri: uri,
+        contractName: next.name,
+        fromVersion: currentVersion,
+        toVersion: currentVersion + 1,
+        kind,
+        ...(reason ? { reason } : {}),
+        diff,
+        ...(effectiveDeadline ? { reconsentDeadline: effectiveDeadline } : {}),
+        reviewUrl,
+        preview,
+    };
+    const result = { version: currentVersion + 1, kind, affectedUsers, preview };
+    if (dryRun) return result;
+    const createdAt = new Date().toISOString();
+    const versionId = uuid();
+    const removedTermPrefixes = diff.removed.map(
+        scope =>
+            `terms.${scope.area}.${scope.type === 'credential' ? 'credentials.categories' : 'personal'}.${scope.key}`
+    );
+    const optionalOffValues: { key: string; value: boolean | string | string[] }[] = diff.added
+        .filter(scope => !scope.required)
+        .flatMap<{ key: string; value: boolean | string | string[] }>(scope => {
+            const prefix = `terms.${scope.area}.${scope.type === 'credential' ? 'credentials.categories' : 'personal'}.${scope.key}`;
+            if (scope.area === 'write') return [{ key: prefix, value: false }];
+            if (scope.type === 'personal') return [];
+            return [
+                { key: `${prefix}.sharing`, value: false },
+                { key: `${prefix}.shared`, value: [] as string[] },
+                { key: `${prefix}.shareAll`, value: false },
+            ];
+        });
+    const disableReadShareAll =
+        kind === 'expanded_optional' &&
+        diff.added.some(
+            scope => scope.area === 'read' && scope.type === 'credential' && !scope.required
+        );
+    const preservedReadGrantKeys = Object.keys(next.contract.read.credentials.categories)
+        .filter(
+            key =>
+                Object.prototype.hasOwnProperty.call(
+                    current.contract.read.credentials.categories,
+                    key
+                ) &&
+                !diff.added.some(
+                    scope =>
+                        scope.area === 'read' && scope.type === 'credential' && scope.key === key
+                )
+        )
+        .map(key => `terms.read.credentials.categories.${key}.shareAll`);
+    const writerIds = [...new Set(next.writers)];
+    const contractProperties = flattenObject({
+        ...Object.fromEntries(
+            Object.entries(next).filter(
+                ([key, value]) =>
+                    value !== undefined &&
+                    ![
+                        'id',
+                        'version',
+                        'createdAt',
+                        'reason',
+                        'kind',
+                        'contract',
+                        'autoboosts',
+                        'writers',
+                    ].includes(key)
+            )
+        ),
+        contract: next.contract,
+        currentVersion: currentVersion + 1,
+        status: 'active',
+        updatedAt: createdAt,
+    });
+    const committed = await neogma.queryRunner.run(
+        `MATCH (c:ConsentFlowContract {id:$id})
+         SET c._contractVersionLock=coalesce(c._contractVersionLock,0)+1
+         WITH c,
+             EXISTS { MATCH (c)-[:CREATED_BY]->(:Profile {profileId:$actor}) } AS authorized,
+             coalesce(c.currentVersion,1) = $expectedVersion AS currentMatches,
+             coalesce(c.status,'active') <> 'retired' AS active
+         FOREACH (_ IN CASE WHEN authorized AND currentMatches AND active THEN [] ELSE [1] END |
+             REMOVE c._contractVersionLock)
+         WITH c WHERE authorized AND currentMatches AND active
+         OPTIONAL MATCH (c)-[:CONSENTS_TO]-(t:ConsentFlowTerms)
+         WITH c, collect(DISTINCT t) AS terms
+         MATCH (c)-[:CREATED_BY]->(owner:Profile)
+         OPTIONAL MATCH (c)-[:CONSENTS_TO]-(holderTerms:ConsentFlowTerms)<-[:CREATED_BY]-(holder:Profile)
+         WHERE holderTerms.status IN ['live','needs_reconsent','suspended']
+         WITH c, terms, owner, collect(DISTINCT holder.profileId) AS holderIds
+         OPTIONAL MATCH (c)-[oldAuto:AUTO_RECEIVE]->(:Boost)
+         WITH c, terms, owner, holderIds, collect(oldAuto) AS oldAuto
+         OPTIONAL MATCH (c)-[oldWriter:CAN_WRITE]->(:Profile)
+         WITH c, terms, owner, holderIds, oldAuto, collect(oldWriter) AS oldWriters
+         OPTIONAL MATCH (boost:Boost) WHERE boost.id IN $boostIds
+         WITH c, terms, owner, holderIds, oldAuto, oldWriters, collect(DISTINCT boost) AS boosts
+         FOREACH (_ IN CASE WHEN size(boosts) = size($boostIds) THEN [] ELSE [1] END | REMOVE c._contractVersionLock)
+         WITH c, terms, owner, holderIds, oldAuto, oldWriters, boosts
+         WHERE size(boosts) = size($boostIds)
+         OPTIONAL MATCH (writer:Profile) WHERE writer.profileId IN $writerIds
+         WITH c, terms, owner, holderIds, oldAuto, oldWriters, boosts, collect(DISTINCT writer) AS writers
+         FOREACH (_ IN CASE WHEN size(writers) = size($writerIds) THEN [] ELSE [1] END | REMOVE c._contractVersionLock)
+         WITH c, terms, owner, holderIds, oldAuto, oldWriters, boosts, writers
+         WHERE size(writers) = size($writerIds)
+         CREATE (v:ConsentFlowContractVersion {id:$versionId, version:$nextVersion, createdAt:$createdAt,
+             contract:$contract, autoboosts:$autoboostSnapshot, writers:$writerSnapshot, reason:$reason, kind:$kind,
+             name:$name, subtitle:$subtitle, description:$description, reasonForAccessing:$reasonForAccessing,
+             image:$image, needsGuardianConsent:$needsGuardianConsent, redirectUrl:$redirectUrl,
+             frontDoorBoostUri:$frontDoorBoostUri, expiresAt:$expiresAt})
+         CREATE (c)-[:HAS_VERSION]->(v)
+         FOREACH (key IN [key IN keys(c)
+             WHERE (key STARTS WITH 'contract.' OR key IN ['name','subtitle','description','reasonForAccessing','image','needsGuardianConsent','redirectUrl','frontDoorBoostUri','expiresAt'])
+                 AND NOT (key IN keys($contractProperties))] | SET c[key]=null)
+         SET c.currentVersion=$nextVersion, c.status='active', c += $contractProperties,
+             c.latestUpdate=$latestUpdate, c.updatedAt=$createdAt
+         FOREACH (relationship IN oldAuto | DELETE relationship)
+         FOREACH (relationship IN oldWriters | DELETE relationship)
+         FOREACH (config IN $autoBoostConfigs |
+             FOREACH (boost IN [target IN boosts WHERE target.id=config.id] |
+                 CREATE (c)-[:AUTO_RECEIVE {signingAuthorityEndpoint:config.signingAuthorityEndpoint,
+                     signingAuthorityName:config.signingAuthorityName, issuer:config.issuer}]->(boost)))
+         FOREACH (writer IN writers | CREATE (c)-[:CAN_WRITE]->(writer))
+         REMOVE c._contractVersionLock
+         FOREACH (term IN terms |
+             FOREACH (_ IN CASE WHEN term.status IN ['live','needs_reconsent','suspended'] THEN [1] ELSE [] END |
+                 SET term.lastReviewedVersion=coalesce(term.lastReviewedVersion,term.consentedVersion,1)
+                 SET term.mutationVersion=coalesce(term.mutationVersion,0)+1
+                 CREATE (transaction:ConsentFlowTransaction {
+                     id:randomUUID(), action:'update', date:$createdAt, version:$nextVersion, kind:$kind
+                 })-[:IS_FOR]->(term))
+             FOREACH (_ IN CASE WHEN term.status = 'live' AND $kind <> 'requires_consent' THEN [1] ELSE [] END |
+                 FOREACH (key IN [key IN keys(term) WHERE any(prefix IN $removedTermPrefixes WHERE key = prefix OR key STARTS WITH prefix + '.')] | SET term[key] = null)
+                 FOREACH (entry IN $optionalOffValues | SET term[entry.key] = entry.value)
+                 FOREACH (_ IN CASE WHEN $disableReadShareAll AND coalesce(term['terms.read.credentials.shareAll'],false) THEN [1] ELSE [] END |
+                     SET term['terms.read.credentials.shareAll']=false
+                     FOREACH (key IN $preservedReadGrantKeys | SET term[key]=true))
+                 FOREACH (_ IN CASE WHEN term['guardianApproval.contractUpdatedAt'] = $previousVersionCreatedAt THEN [1] ELSE [] END |
+                     SET term['guardianApproval.contractUpdatedAt']=$createdAt)
+                 SET term.consentedVersion=$nextVersion,
+                     term.newOptionsUntil=CASE WHEN $kind = 'expanded_optional' THEN $optionsUntil ELSE term.newOptionsUntil END,
+                     term.updatedAt=$createdAt)
+             FOREACH (_ IN CASE WHEN $kind = 'requires_consent' AND term.status = 'live' THEN [1] ELSE [] END |
+                 SET term.status='needs_reconsent', term.reconsentDeadline=coalesce(term.reconsentDeadline,$deadline), term.updatedAt=$createdAt))
+         CREATE (event:ConsentFlowEvent {
+             id:$eventId, contractId:c.id, fromId:owner.profileId, ownerId:owner.profileId,
+             domain:$eventDomain, kind:'contract_updated', payload:$eventPayload,
+             cleanupPending:true, createdAt:$createdAt
+         })
+         FOREACH (holderId IN [id IN holderIds WHERE id <> owner.profileId] |
+             CREATE (event)-[:HAS_DELIVERY]->(:ConsentFlowEventDelivery {
+                 id:event.id + ':' + holderId, toId:holderId, state:'pending',
+                 nextAttemptAt:$createdAt, eventCreatedAt:$createdAt, attempts:0, role:'target'
+             }))
+         RETURN c.currentVersion AS version`,
+        {
+            id: contractId,
+            actor: actorProfileId,
+            expectedVersion: expectedVersion ?? currentVersion,
+            nextVersion: currentVersion + 1,
+            versionId,
+            createdAt,
+            contract: JSON.stringify(next.contract),
+            autoboostSnapshot: JSON.stringify(next.autoboosts),
+            writerSnapshot: JSON.stringify(next.writers),
+            autoBoostConfigs: next.autoboosts,
+            boostIds: next.autoboosts.map(config => config.id),
+            writerIds,
+            reason: reason ?? null,
+            kind,
+            contractProperties,
+            name: next.name,
+            subtitle: next.subtitle ?? null,
+            description: next.description ?? null,
+            reasonForAccessing: next.reasonForAccessing ?? null,
+            image: next.image ?? null,
+            needsGuardianConsent: next.needsGuardianConsent ?? false,
+            redirectUrl: next.redirectUrl ?? null,
+            frontDoorBoostUri: next.frontDoorBoostUri ?? null,
+            expiresAt: next.expiresAt ?? null,
+            latestUpdate: JSON.stringify({
+                fromVersion: currentVersion,
+                toVersion: currentVersion + 1,
+                kind,
+                reason,
+                diff,
+                reconsentDeadline: effectiveDeadline,
+                createdAt,
+                preview,
+            }),
+            deadline: effectiveDeadline ?? null,
+            optionsUntil:
+                kind === 'expanded_optional'
+                    ? new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toISOString()
+                    : null,
+            removedTermPrefixes,
+            optionalOffValues,
+            disableReadShareAll,
+            preservedReadGrantKeys,
+            previousVersionCreatedAt: current.createdAt,
+            eventId,
+            eventDomain: domain,
+            eventPayload: JSON.stringify(notificationData),
+        }
+    );
+    if (!committed.records.length)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'Contract changed concurrently; retry the update',
+        });
+    await tryDispatchContractEvent(eventId);
+    return result;
+};