@learncard/network-brain-service 4.0.2 → 4.0.3

package/src/accesslayer/boost/relationships/read.ts

@@ -324,6 +324,59 @@ export const getBoostByUriWithDefaultClaimPermissions = async (
     };
 };
 
+/** Every send of the boost bound as `$boostId`: binds `source`, `credential`, `sent`, `sender`. */
+const MATCH_BOOST_SENDS = `MATCH (source:Boost {id: $boostId})<-[:INSTANCE_OF]-(credential:Credential)<-[sent:CREDENTIAL_SENT]-(sender:Profile)`;
+
+/**
+ * Same rows as MATCH_BOOST_SENDS, but the boost's credentials are collected first and the sends
+ * are then matched from each credential.
+ *
+ * The aim is to keep the cost tied to this boost's own sends. With a range or IN predicate on
+ * `sent.date` / `sent.to`, the planner can otherwise start from credential_sent_date_idx or
+ * credential_sent_to_idx across every boost and filter down to this one afterwards, which for a
+ * small boost reads far more sends than the boost has.
+ *
+ * This nudges the planner toward expanding from each credential; it doesn't guarantee that plan.
+ * With unsampled or stale index statistics, Neo4j has still been seen to run a global
+ * credential_sent_date_idx scan once per credential. If a change here matters, check the real plan
+ * with PROFILE, and refresh index statistics if it shows that scan. `carry` lists variables from
+ * earlier clauses that later clauses still need.
+ */
+const matchBoostSendsFromBoost = (carry: string[] = []): string =>
+    `MATCH (source:Boost {id: $boostId})<-[:INSTANCE_OF]-(boostCredential:Credential)
+    WITH ${[...carry, 'collect(boostCredential) AS boostCredentials'].join(', ')}
+    UNWIND boostCredentials AS credential
+    MATCH (credential)<-[sent:CREDENTIAL_SENT]-(sender:Profile)`;
+
+/**
+ * When a recipient profile query pins `profileId` to a value (or an `$in` list), the join
+ * `recipient.profileId = sent.to` means the same condition holds for `sent.to`. Applying it to
+ * the send first lets the query skip the Profile lookup for every other send.
+ *
+ * Mirrors buildWhereClause: a document-level `$or` ignores every other key, so no prefilter then.
+ */
+const getSentToPrefilter = (
+    convertedQuery: Record<string, unknown>
+): { clause: string; params: Record<string, unknown> } | undefined => {
+    if (!convertedQuery || '$or' in convertedQuery) return undefined;
+
+    const value = convertedQuery.profileId;
+
+    if (typeof value === 'string') {
+        return { clause: 'sent.to = $sentToPrefilter', params: { sentToPrefilter: value } };
+    }
+
+    if (value && typeof value === 'object' && Object.keys(value).length === 1) {
+        const inList = (value as { $in?: unknown }).$in;
+
+        if (Array.isArray(inList)) {
+            return { clause: 'sent.to IN $sentToPrefilter', params: { sentToPrefilter: inList } };
+        }
+    }
+
+    return undefined;
+};
+
 /**
  * Query to get the recipients of a boost. Cipher Code is:
  * MATCH (source:`Boost` { id: $id })<-[instanceOf:INSTANCE_OF]-(credential:`Credential`)-[received:CREDENTIAL_RECEIVED]->(recipient:`Profile`)
@@ -352,26 +405,35 @@ export const getBoostRecipients = async (
         convertedQuery as any
     );
 
-    const _query = new QueryBuilder(new BindParam({ cursor, from, ...queryParams }))
-        .match({
-            related: [
-                { identifier: 'source', model: Boost, where: { id: boost.id } },
-                {
-                    ...Credential.getRelationshipByAlias('instanceOf'),
-                    identifier: 'instanceOf',
-                    direction: 'in',
-                },
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Profile.getRelationshipByAlias('credentialSent'),
-                    identifier: 'sent',
-                    direction: 'in',
-                },
-                { identifier: 'sender', model: Profile },
-            ],
+    const sentToPrefilter = getSentToPrefilter(convertedQuery);
+
+    // Filter and sort the sends before touching recipient Profiles. The Profile lookup and the
+    // CREDENTIAL_RECEIVED expand then only run until LIMIT is satisfied, instead of once per send.
+    const sendFilters = [
+        ...(from ? ['sender.profileId = $from'] : []),
+        ...(cursor ? ['sent.date > $cursor'] : []),
+        ...(sentToPrefilter ? [sentToPrefilter.clause] : []),
+    ];
+
+    const query = new QueryBuilder(
+        new BindParam({
+            boostId: boost.id,
+            cursor,
+            from,
+            ...queryParams,
+            ...sentToPrefilter?.params,
         })
+    )
+        .raw(
+            // An equality on sent.to or the sender's profileId is selective enough to start from;
+            // otherwise try to read the sends from the boost (see matchBoostSendsFromBoost)
+            sentToPrefilter || from ? MATCH_BOOST_SENDS : matchBoostSendsFromBoost()
+        )
+        .raw(sendFilters.length > 0 ? `WHERE ${sendFilters.join(' AND ')}` : '')
+        .with('sender, sent, credential')
+        .orderBy('sent.date')
         .match({ model: Profile, identifier: 'recipient' })
-        .where(`recipient.profileId = sent.to${from ? ' AND sender.profileId = $from' : ''}`)
+        .where('recipient.profileId = sent.to')
         .match({
             optional: includeUnacceptedBoosts,
             related: [
@@ -391,8 +453,6 @@ export const getBoostRecipients = async (
             }`
         );
 
-    const query = cursor ? _query.raw('AND sent.date > $cursor') : _query;
-
     const results = convertQueryResultToPropertiesObjectArray<{
         sender: FlatProfileType;
         sent: ProfileRelationships['credentialSent']['RelationshipProperties'];
@@ -414,10 +474,7 @@ export const getBoostRecipients = async (
         received: received?.date,
         ...(credential && { uri: getCredentialUri(credential.id, domain) }),
         status: coalesceStatus(sent.status, received?.status) as
-            | 'active'
-            | 'revoked'
-            | 'suspended'
-            | undefined,
+            'active' | 'revoked' | 'suspended' | undefined,
     }));
 
     const recipients = await getProfilesByProfileIds(resultsWithIds.map(result => result.to));
@@ -512,10 +569,7 @@ export const getBoostRecipientsSkipLimit = async (
         received: received?.date,
         ...(credential && { uri: getCredentialUri(credential.id, domain) }),
         status: coalesceStatus(sent.status, received?.status) as
-            | 'active'
-            | 'revoked'
-            | 'suspended'
-            | undefined,
+            'active' | 'revoked' | 'suspended' | undefined,
     }));
 
     const recipients = await getProfilesByProfileIds(resultsWithIds.map(result => result.to));
@@ -990,7 +1044,7 @@ export const getConnectedBoostRecipients = async (
         convertedQuery as any
     );
 
-    const _query = new QueryBuilder(new BindParam({ cursor, ...queryParams }))
+    const query = new QueryBuilder(new BindParam({ boostId: boost.id, cursor, ...queryParams }))
         // Build connection list
         .match({
             model: Profile,
@@ -1141,23 +1195,11 @@ export const getConnectedBoostRecipients = async (
         .unwind('allConnectedProfiles AS conn')
         .with('COLLECT(DISTINCT conn.profileId) AS connectionIds')
         // --- Boost recipient matching ---
-        .match({
-            related: [
-                { identifier: 'source', model: Boost, where: { id: boost.id } },
-                {
-                    ...Credential.getRelationshipByAlias('instanceOf'),
-                    identifier: 'instanceOf',
-                    direction: 'in',
-                },
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Profile.getRelationshipByAlias('credentialSent'),
-                    identifier: 'sent',
-                    direction: 'in',
-                },
-                { identifier: 'sender', model: Profile },
-            ],
-        })
+        .raw(matchBoostSendsFromBoost(['connectionIds']))
+        // Narrow and sort the sends first so the Profile lookup only runs until LIMIT is met
+        .raw(`WHERE sent.to IN connectionIds${cursor ? ' AND sent.date > $cursor' : ''}`)
+        .with('sender, sent, credential')
+        .orderBy('sent.date')
         .match({ model: Profile, identifier: 'recipient' })
         .where('recipient.profileId = sent.to')
         .match({
@@ -1171,10 +1213,8 @@ export const getConnectedBoostRecipients = async (
                 { identifier: 'recipient' },
             ],
         })
-        .with('sender, sent, received, recipient, credential, connectionIds')
-        .where(`sent.to IN connectionIds AND ${recipientWhereClause}`);
-
-    const query = cursor ? _query.raw('AND sent.date > $cursor') : _query;
+        .with('sender, sent, received, recipient, credential')
+        .where(recipientWhereClause);
 
     const results = convertQueryResultToPropertiesObjectArray<{
         sender: FlatProfileType;
@@ -1208,6 +1248,44 @@ export const getConnectedBoostRecipients = async (
         .filter(result => Boolean(result.to)) as Array<BoostRecipientInfo & { sent: string }>;
 };
 
+/**
+ * Tail of a recipient count, continuing from a MATCH that bound `credential` and `sent`.
+ * Produces one `to` row per distinct recipient profileId, ready for `RETURN COUNT(to)`.
+ *
+ * Same answer as joining `(recipient:Profile {profileId: sent.to})` (plus the CREDENTIAL_RECEIVED
+ * edge into it when unaccepted sends are excluded) on every send and counting distinct ids, but it
+ * looks each profile up once per distinct id and stops at the first match.
+ */
+const buildDistinctRecipientCount = ({
+    includeUnacceptedBoosts,
+    recipientWhereClause,
+    profileKnownToExist,
+}: {
+    includeUnacceptedBoosts: boolean;
+    recipientWhereClause: string;
+    profileKnownToExist: boolean;
+}): string => {
+    const hasProfileFilter = Boolean(recipientWhereClause) && recipientWhereClause !== 'true';
+    const profileFilter = hasProfileFilter ? ` AND ${recipientWhereClause}` : '';
+
+    if (!includeUnacceptedBoosts) {
+        return `WITH DISTINCT credential, sent.to AS to
+            WHERE EXISTS {
+                MATCH (credential)-[:CREDENTIAL_RECEIVED]->(recipient:Profile)
+                WHERE recipient.profileId = to${profileFilter}
+            }
+            WITH DISTINCT to`;
+    }
+
+    if (profileKnownToExist && !hasProfileFilter) return 'WITH DISTINCT sent.to AS to';
+
+    return `WITH DISTINCT sent.to AS to
+        WHERE EXISTS {
+            MATCH (recipient:Profile)
+            WHERE recipient.profileId = to${profileFilter}
+        }`;
+};
+
 /**
  * Count boost recipients that are connected with the requesting profile
  */
@@ -1223,7 +1301,7 @@ export const countConnectedBoostRecipients = async (
     const { whereClause: countRecipientWhereClause, params: countQueryParams } =
         buildWhereForQueryBuilder('recipient', convertedQuery as any);
 
-    const countQuery = new QueryBuilder(new BindParam({ ...countQueryParams }))
+    const countQuery = new QueryBuilder(new BindParam({ boostId: boost.id, ...countQueryParams }))
         // Build connection list
         .match({
             model: Profile,
@@ -1374,40 +1452,18 @@ export const countConnectedBoostRecipients = async (
         .unwind('allConnectedProfiles AS conn')
         .with('COLLECT(DISTINCT conn.profileId) AS connectionIds')
         // --- Boost recipient matching ---
-        .match({
-            related: [
-                { identifier: 'source', model: Boost, where: { id: boost.id } },
-                {
-                    ...Credential.getRelationshipByAlias('instanceOf'),
-                    identifier: 'instanceOf',
-                    direction: 'in',
-                },
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Profile.getRelationshipByAlias('credentialSent'),
-                    identifier: 'sent',
-                    direction: 'in',
-                },
-                { identifier: 'sender', model: Profile },
-            ],
-        })
-        .match({ model: Profile, identifier: 'recipient' })
-        .where('recipient.profileId = sent.to')
-        .match({
-            optional: includeUnacceptedBoosts,
-            related: [
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Credential.getRelationshipByAlias('credentialReceived'),
-                    identifier: 'received',
-                },
-                { identifier: 'recipient' },
-            ],
-        })
-        .with('sender, sent, received, recipient, credential, connectionIds')
-        .where(`sent.to IN connectionIds AND ${countRecipientWhereClause}`);
+        .raw(matchBoostSendsFromBoost(['connectionIds']))
+        .raw('WHERE sent.to IN connectionIds')
+        .raw(
+            buildDistinctRecipientCount({
+                includeUnacceptedBoosts,
+                recipientWhereClause: countRecipientWhereClause,
+                // Every id in connectionIds was read off a Profile node, so the Profile always exists
+                profileKnownToExist: true,
+            })
+        );
 
-    const result = await countQuery.return('COUNT(DISTINCT sent.to) AS count').run();
+    const result = await countQuery.return('COUNT(to) AS count').run();
 
     return Number(result.records[0]?.get('count') ?? 0);
 };
@@ -1493,31 +1549,26 @@ export const getBoostRecipientsWithChildren = async (
                 { identifier: 'sender', model: Profile },
             ],
         })
-        .match({ model: Profile, identifier: 'recipient' })
-        .where('recipient.profileId = sent.to')
-        // Optional match for received credentials
-        .match({
-            optional: includeUnacceptedBoosts,
-            related: [
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Credential.getRelationshipByAlias('credentialReceived'),
-                    identifier: 'received',
-                },
-                { identifier: 'recipient' },
-            ],
-        })
-        // Group by recipient and collect boost data first
+        // Read the received edge off the credential (one hop) rather than looking up a Profile
+        // for every send. The recipient Profile is only looked up per page row further down.
+        .raw(
+            `${includeUnacceptedBoosts ? 'OPTIONAL ' : ''}MATCH (credential)-[received:CREDENTIAL_RECEIVED]->(receivedBy:Profile)
+            WHERE receivedBy.profileId = sent.to`
+        )
+        // Group by recipient profileId and collect boost data first
         .with(
-            `recipient, 
+            `sent.to AS to,
                COLLECT(DISTINCT {relevantBoost: relevantBoost, sender: sender, sent: sent, received: received, credential: credential}) AS boostData`
         )
+        .raw(cursor ? 'WHERE NOT to <= $cursor' : '')
+        .orderBy('to ASC')
+        .match({ model: Profile, identifier: 'recipient' })
+        .where('recipient.profileId = to')
+        .with('to, recipient, boostData')
         // Apply profile query filtering after grouping
         .where(profileWhereClause)
-        // Add cursor filtering if provided
-        .raw(cursor ? 'AND recipient.profileId > $cursor' : '')
         // Order by profileId and limit profiles (not individual boost relationships)
-        .orderBy('recipient.profileId ASC')
+        .orderBy('to ASC')
         .limit(limit)
         .unwind('boostData AS data')
         .return(
@@ -1547,10 +1598,7 @@ export const getBoostRecipientsWithChildren = async (
                 boostUri: getBoostUri(boostId, domain),
                 ...(credential && { uri: getCredentialUri(credential.id, domain) }),
                 status: coalesceStatus(sent.status, received?.status) as
-                    | 'active'
-                    | 'revoked'
-                    | 'suspended'
-                    | undefined,
+                    'active' | 'revoked' | 'suspended' | undefined,
             };
         });
 
@@ -1663,26 +1711,15 @@ export const countBoostRecipientsWithChildren = async (
                 { identifier: 'sender', model: Profile },
             ],
         })
-        .match({ model: Profile, identifier: 'recipient' })
-        .where('recipient.profileId = sent.to')
-        // Optional match for received credentials
-        .match({
-            optional: includeUnacceptedBoosts,
-            related: [
-                { identifier: 'credential', model: Credential },
-                {
-                    ...Credential.getRelationshipByAlias('credentialReceived'),
-                    identifier: 'received',
-                },
-                { identifier: 'recipient' },
-            ],
-        })
-        // Reduce to recipient before applying filter to ensure it doesn't attach to OPTIONAL MATCH
-        .with('recipient')
-        // Apply profile query filtering after WITH so it filters rows, not optional pattern
-        .where(countProfileWhereClause);
+        .raw(
+            buildDistinctRecipientCount({
+                includeUnacceptedBoosts,
+                recipientWhereClause: countProfileWhereClause,
+                profileKnownToExist: false,
+            })
+        );
 
-    const result = await _query.return('COUNT(DISTINCT recipient.profileId) AS count').run();
+    const result = await _query.return('COUNT(to) AS count').run();
 
     return Number(result.records[0]?.get('count') ?? 0);
 };

package/src/accesslayer/profile/create.ts

@@ -5,6 +5,7 @@ import { LCNProfile } from '@learncard/types';
 import { Profile } from '@models';
 import { BindParam, QueryBuilder } from 'neogma';
 import { ProfileType } from 'types/profile';
+import { syncProfileDisplayNameLower } from './search-fields';
 
 export const createProfile = async (input: LCNProfile): Promise<ProfileType> => {
     const result = await new QueryBuilder(
@@ -13,7 +14,7 @@ export const createProfile = async (input: LCNProfile): Promise<ProfileType> =>
         })
     )
         .create({ model: Profile, identifier: 'profile' })
-        .set('profile += $params')
+        .set(`profile += $params, ${syncProfileDisplayNameLower('profile')}`)
         .return('profile')
         .limit(1)
         .run();

package/src/accesslayer/profile/read.ts

@@ -3,6 +3,7 @@ import { Profile } from '@models';
 import { ProfileType, FlatProfileType } from 'types/profile';
 import { transformProfileId } from '@helpers/profile.helpers';
 import { inflateObject } from '@helpers/objects.helpers';
+import { PROFILE_DISPLAY_NAME_LOWER_FIELD, normalizeProfileSearchText } from './search-fields';
 
 export const getProfileByProfileId = async (profileId: string): Promise<ProfileType | null> => {
     const result = await new QueryBuilder()
@@ -86,6 +87,15 @@ export const checkIfProfileExists = async ({
     return false;
 };
 
+/**
+ * Case-insensitive substring search over `profileId` and `displayName`.
+ *
+ * Each branch of the `UNION` is a single `CONTAINS` predicate so the planner can seek a TEXT
+ * index for it (`profileId_text_idx` and `profile_displayname_lower_text_idx`) instead of
+ * scanning every `Profile`. `UNION` (not `UNION ALL`) dedupes a profile that matches both.
+ * The visibility/private/service/blacklist filters, ordering and limit are applied to the
+ * merged set, same as before.
+ */
 export const searchProfiles = async (
     searchInput: string,
     {
@@ -100,15 +110,25 @@ export const searchProfiles = async (
 ): Promise<ProfileType[]> => {
     const result = await new QueryBuilder(
         new BindParam({
+            // profileId is stored lowercased by transformProfileId
             input: searchInput.toLowerCase(),
-            inputRegex: `(?i).*${searchInput}.*`,
+            // normalized in Cypher below with the same expression displayNameLower is written with
+            displayNameInput: searchInput,
             blacklist,
         })
     )
-        .match({ identifier: 'profile', model: Profile })
+        .raw(
+            `CALL {
+    MATCH (profile:Profile) WHERE profile.profileId CONTAINS $input RETURN profile
+    UNION
+    MATCH (profile:Profile) WHERE profile.${PROFILE_DISPLAY_NAME_LOWER_FIELD} CONTAINS ${normalizeProfileSearchText(
+        '$displayNameInput'
+    )} RETURN profile
+}`
+        )
+        .with('profile')
         .where(
             `
-(profile.profileId CONTAINS $input OR profile.displayName =~ $inputRegex) AND 
 (
     profile.profileVisibility IS NULL OR
     profile.profileVisibility = "public"

package/src/accesslayer/profile/search-fields.ts

@@ -0,0 +1,69 @@
+/**
+ * Profile search runs `CONTAINS` against TEXT indexes, and TEXT index `CONTAINS` is case-sensitive.
+ * `profileId` is already stored lowercased (`transformProfileId`), so it can be searched as-is.
+ * `displayName` keeps the casing people typed, so we keep a normalized copy of it in
+ * `displayNameLower` (TEXT-indexed by `profile_displayname_lower_text_idx`) and search that.
+ *
+ * Every write that sets `displayName` must also set `displayNameLower`, and writes, the backfill
+ * and the search input all go through the same Cypher expression, `normalizeProfileSearchText`.
+ */
+export const PROFILE_DISPLAY_NAME_LOWER_FIELD = 'displayNameLower';
+
+/**
+ * The one search normalization for display names: Cypher `toLower`, then final sigma (ς, U+03C2)
+ * folded to σ (U+03C3).
+ *
+ * `toLower` alone isn't safe for substring matching because it's context-sensitive for Greek:
+ * a capital Σ becomes ς at the end of a word and σ everywhere else. So `ΑΝΑΣΤΑΣΙΑ` is stored as
+ * `αναστασια`, but the search input `ΑΝΑΣ` lowercases to `ανας` and no longer matches. Folding ς to
+ * σ afterwards makes the result the same for a letter wherever it sits in the string, so a
+ * substring of a name always normalizes to a substring of the normalized name.
+ *
+ * Use this for writes, the backfill and queries alike. Changing it means re-running the backfill.
+ */
+export const normalizeProfileSearchText = (expression: string): string =>
+    `replace(toLower(${expression}), '\u03C2', '\u03C3')`;
+
+/** Cypher fragment that keeps `displayNameLower` in sync with `displayName` for `identifier`. */
+export const syncProfileDisplayNameLower = (identifier: string): string =>
+    `${identifier}.${PROFILE_DISPLAY_NAME_LOWER_FIELD} = ${normalizeProfileSearchText(
+        `${identifier}.displayName`
+    )}`;
+
+/** Cypher predicate: true for a profile whose `displayNameLower` is missing or stale. */
+export const profileDisplayNameLowerIsStale = (identifier: string): string =>
+    `${identifier}.displayName IS NOT NULL
+  AND (${identifier}.${PROFILE_DISPLAY_NAME_LOWER_FIELD} IS NULL
+       OR ${identifier}.${PROFILE_DISPLAY_NAME_LOWER_FIELD} <> ${normalizeProfileSearchText(
+           `${identifier}.displayName`
+       )})`;
+
+/**
+ * One-pass, idempotent backfill for profiles written before `displayNameLower` existed (or whose
+ * copy has drifted). Uses `CALL { ... } IN TRANSACTIONS`, so it has to run in an auto-commit
+ * transaction (e.g. `session.run`), not inside an explicit transaction.
+ */
+export const buildBackfillProfileDisplayNameLowerQuery = (batchSize = 1000): string => `
+MATCH (profile:Profile)
+WHERE ${profileDisplayNameLowerIsStale('profile')}
+CALL {
+    WITH profile
+    SET ${syncProfileDisplayNameLower('profile')}
+} IN TRANSACTIONS OF ${Number.isFinite(batchSize) ? Math.max(1, Math.floor(batchSize)) : 1000} ROWS
+`;
+
+/** Anything that runs a query in an auto-commit transaction, e.g. `query => session.run(query)`. */
+export type AutoCommitRunner = (
+    query: string
+) => PromiseLike<{ summary: { counters: { updates: () => Record<string, number> } } }>;
+
+/** Runs the backfill and returns how many profiles were updated. */
+export const backfillProfileDisplayNameLower = async (
+    run: AutoCommitRunner,
+    { batchSize = 1000 }: { batchSize?: number } = {}
+): Promise<number> => {
+    // The batch size is inlined: OF ... ROWS needs an integer and JS numbers bind as floats.
+    const result = await run(buildBackfillProfileDisplayNameLowerQuery(batchSize));
+
+    return result.summary.counters.updates().propertiesSet ?? 0;
+};

package/src/accesslayer/profile/update.ts

@@ -2,6 +2,7 @@ import { QueryBuilder, BindParam } from 'neogma';
 import { flattenObject } from '@helpers/objects.helpers';
 import { Profile } from '@models';
 import { ProfileType } from 'types/profile';
+import { syncProfileDisplayNameLower } from './search-fields';
 
 export const updateProfile = async (profile: ProfileType, updates: Partial<ProfileType>) => {
     const currentDisplay = profile.display;
@@ -14,7 +15,12 @@ export const updateProfile = async (profile: ProfileType, updates: Partial<Profi
 
     const query = new QueryBuilder(new BindParam({ params: newUpdates }))
         .match({ model: Profile, where: { profileId: profile.profileId }, identifier: 'profile' })
-        .set('profile += $params');
+        .set(
+            // Keep the lowercased search copy in sync whenever displayName changes
+            'displayName' in newUpdates
+                ? `profile += $params, ${syncProfileDisplayNameLower('profile')}`
+                : 'profile += $params'
+        );
 
     const result = await query.run();
 

package/src/models/credential-refresh-constraints.test.ts

@@ -77,4 +77,48 @@ describe('credential refresh constraint readiness', () => {
 
         expect(mocks.run).toHaveBeenCalledTimes(9);
     });
+
+    it('runs the constraint setup once per process across many calls', async () => {
+        mocks.run.mockResolvedValue(undefined);
+
+        const { ensureCredentialRefreshConstraints } =
+            await import('./credential-refresh-constraints');
+
+        // A burst of concurrent callers (cold start plus the first requests) ...
+        await Promise.all(Array.from({ length: 50 }, () => ensureCredentialRefreshConstraints()));
+        // ... and every later caller in the same process.
+        for (let i = 0; i < 200; i++) await ensureCredentialRefreshConstraints();
+
+        expect(mocks.run).toHaveBeenCalledTimes(8);
+        expect(new Set(mocks.run.mock.calls.map(([query]) => query)).size).toBe(8);
+    });
+
+    it('retries transient errors and deadlocks before giving up on a statement', async () => {
+        mocks.run
+            .mockRejectedValueOnce({ code: 'Neo.TransientError.Transaction.DeadlockDetected' })
+            .mockRejectedValueOnce({
+                code: 'Neo.TransientError.Transaction.LockClientStopped',
+                retriable: true,
+            })
+            .mockResolvedValue(undefined);
+
+        const { ensureCredentialRefreshConstraints } =
+            await import('./credential-refresh-constraints');
+
+        await expect(ensureCredentialRefreshConstraints()).resolves.toBeUndefined();
+        // The first statement took three attempts, the other seven one each
+        expect(mocks.run).toHaveBeenCalledTimes(10);
+        expect(mocks.run.mock.calls[0]![0]).toBe(mocks.run.mock.calls[2]![0]);
+    });
+
+    it('does not retry a non-transient failure', async () => {
+        const setupFailure = { code: 'Neo.ClientError.Security.Forbidden' };
+        mocks.run.mockRejectedValueOnce(setupFailure).mockResolvedValue(undefined);
+
+        const { ensureCredentialRefreshConstraints } =
+            await import('./credential-refresh-constraints');
+
+        await expect(ensureCredentialRefreshConstraints()).rejects.toBe(setupFailure);
+        expect(mocks.run).toHaveBeenCalledTimes(1);
+    });
 });

package/src/models/credential-refresh-constraints.ts

@@ -13,24 +13,50 @@ const CREDENTIAL_REFRESH_CONSTRAINT_QUERIES = [
 
 type Neo4jSchemaError = {
     code?: string;
+    retriable?: boolean;
 };
 
+const MAX_ATTEMPTS = 5;
+
+const wait = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
 const isEquivalentSchemaRuleRace = (error: unknown): boolean =>
     (error as Neo4jSchemaError | undefined)?.code ===
     'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists';
 
-const createCredentialRefreshConstraints = async (): Promise<void> => {
-    for (const query of CREDENTIAL_REFRESH_CONSTRAINT_QUERIES) {
+// Same retry rule as the index setup in models/index.ts: transient errors and deadlocks
+// (schema locks contended by other cold starts) are retried with a short backoff.
+const isRetriable = (error: unknown): boolean => {
+    const neo4jError = error as Neo4jSchemaError | undefined;
+
+    return (
+        neo4jError?.retriable === true ||
+        neo4jError?.code === 'Neo.TransientError.Transaction.DeadlockDetected'
+    );
+};
+
+const runConstraintQuery = async (query: string): Promise<void> => {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
         try {
             await neogma.queryRunner.run(query);
+            return;
         } catch (error) {
             // Concurrent service starts can both observe a missing rule before one wins
             // creation. The losing CREATE is equivalent to the desired ready state.
-            if (!isEquivalentSchemaRuleRace(error)) throw error;
+            if (isEquivalentSchemaRuleRace(error)) return;
+            if (!isRetriable(error) || attempt === MAX_ATTEMPTS) throw error;
+
+            await wait(100 * attempt);
         }
     }
 };
 
+const createCredentialRefreshConstraints = async (): Promise<void> => {
+    for (const query of CREDENTIAL_REFRESH_CONSTRAINT_QUERIES) {
+        await runConstraintQuery(query);
+    }
+};
+
 let constraintReadiness: Promise<void> | undefined;
 
 /**