@learncard/network-brain-service 4.0.2 → 4.0.4

package/dist/routes/workflows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/routes/workflows.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAgB,OAAO,EAAE,MAAM,SAAS,CAAC;AAuFhD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqF1B,CAAC;AA8uBH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC"}
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/routes/workflows.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAgB,OAAO,EAAE,MAAM,SAAS,CAAC;AA4FhD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqF1B,CAAC;AAgvBH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC"}

package/dist/seed/seedSkillFrameworks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seedSkillFrameworks.d.ts","sourceRoot":"","sources":["../../src/seed/seedSkillFrameworks.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAehC,KAAK,eAAe,GAAG;IACnB,GAAG,EAAE,CACD,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CACvE,CAAC;AAEF,KAAK,UAAU,GAAG;IACd,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CACnC,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAgCF,eAAO,MAAM,gCAAgC,QAAO,MAGI,CAAC;AAoLzD,eAAO,MAAM,oCAAoC,GAC7C,QAAO,OAAO,GAAG,SAAmB,KACrC,OAAO,CAAC;IACP,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,wBAAwB,CAAC;CACvC,CA2DA,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,KAAK,eAAe,CAAC,KAAK,CAAC,KAAG,OAAO,CAAC,MAAM,CAGtF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,KAAK,eAAe,CAAC,KAAK,CAAC,KAAG,OAAO,CAAC,OAAO,CAElF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAC/B,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,WAAW,MAAM,KAClB,OAAO,CAAC,MAAM,CAwBhB,CAAC;AA6IF,eAAO,MAAM,iBAAiB,GAC1B,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,YAAW,MAAiC,KAC7C,OAAO,CAAC,IAAI,CA0Bd,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACnC,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,UAAS,0BAA+B,KACzC,OAAO,CAAC;IAAE,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,CAgG1C,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACrC,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,UAAS,0BAA+B,KACzC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,CAoC3D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,KAAG,MAAM,EAMzD,CAAC"}
+{"version":3,"file":"seedSkillFrameworks.d.ts","sourceRoot":"","sources":["../../src/seed/seedSkillFrameworks.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAiBhC,KAAK,eAAe,GAAG;IACnB,GAAG,EAAE,CACD,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;CACvE,CAAC;AAEF,KAAK,UAAU,GAAG;IACd,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CACnC,CAAC;AAEF,KAAK,0BAA0B,GAAG;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;CACpB,CAAC;AAEF,KAAK,wBAAwB,GAAG;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAgCF,eAAO,MAAM,gCAAgC,QAAO,MAGI,CAAC;AAoLzD,eAAO,MAAM,oCAAoC,GAC7C,QAAO,OAAO,GAAG,SAAmB,KACrC,OAAO,CAAC;IACP,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,wBAAwB,CAAC;CACvC,CA2DA,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,KAAK,eAAe,CAAC,KAAK,CAAC,KAAG,OAAO,CAAC,MAAM,CAGtF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,KAAK,eAAe,CAAC,KAAK,CAAC,KAAG,OAAO,CAAC,OAAO,CAElF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAC/B,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,WAAW,MAAM,KAClB,OAAO,CAAC,MAAM,CAwBhB,CAAC;AA6IF,eAAO,MAAM,iBAAiB,GAC1B,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,YAAW,MAAiC,KAC7C,OAAO,CAAC,IAAI,CA2Bd,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACnC,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,UAAS,0BAA+B,KACzC,OAAO,CAAC;IAAE,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,CAgG1C,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACrC,KAAK,eAAe,CAAC,KAAK,CAAC,EAC3B,UAAS,0BAA+B,KACzC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,CAoC3D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,KAAG,MAAM,EAMzD,CAAC"}

package/esbuildPlugins.cjs

@@ -2,6 +2,7 @@ const path = require('node:path');
 const fs = require('node:fs');
 
 const { sentryEsbuildPlugin } = require('@sentry/esbuild-plugin');
+const { withSentryRateLimitRetry } = require('../../../scripts/sentry-rate-limit-retry.cjs');
 
 const forceCjsSodiumWrapperPlugin = {
     name: 'force-cjs-sodium-wrapper',
@@ -40,10 +41,12 @@ const copyDidkitWasmPlugin = {
 module.exports = [
     forceCjsSodiumWrapperPlugin,
     copyDidkitWasmPlugin,
-    sentryEsbuildPlugin({
-        telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
-        authToken: process.env.SENTRY_AUTH_TOKEN,
-        org: process.env.SENTRY_ORG,
-        project: process.env.SENTRY_PROJECT,
-    }),
+    withSentryRateLimitRetry(
+        sentryEsbuildPlugin({
+            telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
+            authToken: process.env.SENTRY_AUTH_TOKEN,
+            org: process.env.SENTRY_ORG,
+            project: process.env.SENTRY_PROJECT,
+        })
+    ),
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-brain-service",
-    "version": "4.0.2",
+    "version": "4.0.4",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -16,11 +16,14 @@
         "test:coverage": "vitest run --coverage --config vitest.config.ts",
         "test:integration": "vitest run --config vitest.integration.config.ts",
         "test:inbox:e2e": "vitest run --config vitest.inbox-e2e.config.ts",
+        "test:profile-search": "vitest run --config vitest.profile-search-neo4j.config.ts",
         "test:integration:watch": "vitest --config vitest.integration.config.ts",
         "test:docker": "vitest run --config vitest.integration.config.ts",
+        "test:boost-recipients": "vitest run --config vitest.boost-recipients-neo4j.config.ts",
         "seed:dev-app": "bun scripts/seed-dev-app.ts",
         "seed:demo-persona": "bun --conditions=development scripts/seed-demo-persona.ts",
         "skill-frameworks": "bun scripts/skill-frameworks.ts",
+        "backfill:profile-search": "bun scripts/backfill-profile-search.ts",
         "build": "shx rm -rf dist && node bundle.mjs && tsc --p tsconfig.build.json && tsc --showConfig --p tsconfig.build.json > tsconfig.temp.json && tsc-alias --replacer ./tsc-alias-replacer.cjs -p tsconfig.temp.json && shx rm tsconfig.temp.json",
         "typecheck": "tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p tsconfig.entrypoints.json",
         "build:docker": "shx rm -rf build && node esbuild-docker.mjs",
@@ -62,23 +65,23 @@
         "@digitalcredentials/issuer-registry-client": "^4.1.0",
         "@fastify/cors": "^11.2.0",
         "@google/genai": "^1.27.0",
-        "@learncard/credential-library": "2.1.2",
-        "@learncard/core": "9.4.39",
-        "@learncard/crypto-plugin": "1.1.39",
-        "@learncard/did-web-plugin": "1.1.39",
-        "@learncard/didkey-plugin": "1.1.39",
-        "@learncard/didkit-plugin": "1.10.4",
-        "@learncard/didkit-plugin-node": "0.3.4",
-        "@learncard/dynamic-loader-plugin": "1.1.39",
-        "@learncard/encryption-plugin": "1.1.39",
-        "@learncard/expiration-plugin": "1.2.39",
+        "@learncard/credential-library": "2.1.3",
+        "@learncard/core": "9.4.40",
+        "@learncard/crypto-plugin": "1.1.40",
+        "@learncard/did-web-plugin": "1.1.40",
+        "@learncard/didkey-plugin": "1.1.40",
+        "@learncard/didkit-plugin": "1.10.5",
+        "@learncard/didkit-plugin-node": "0.3.5",
+        "@learncard/dynamic-loader-plugin": "1.1.40",
+        "@learncard/encryption-plugin": "1.1.40",
+        "@learncard/expiration-plugin": "1.2.40",
         "@learncard/email-templates": "1.2.1",
-        "@learncard/helpers": "1.6.3",
-        "@learncard/learn-card-plugin": "1.2.39",
+        "@learncard/helpers": "1.7.0",
+        "@learncard/learn-card-plugin": "1.2.40",
         "@learncard/partner-connect-core": "0.2.0",
-        "@learncard/types": "5.23.1",
-        "@learncard/vc-plugin": "1.6.5",
-        "@learncard/vc-templates-plugin": "1.1.39",
+        "@learncard/types": "5.23.2",
+        "@learncard/vc-plugin": "1.6.6",
+        "@learncard/vc-templates-plugin": "1.1.40",
         "@sentry/serverless": "7.61.0",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",

package/project.json

@@ -111,12 +111,30 @@
                 "script": "test:inbox:e2e"
             }
         },
+        "test:profile-search": {
+            "executor": "nx:run-script",
+            "cache": false,
+            "dependsOn": ["^build"],
+            "inputs": ["source", "tests", "{projectRoot}/vitest.profile-search-neo4j.config.ts"],
+            "options": {
+                "script": "test:profile-search"
+            }
+        },
         "test:integration": {
             "executor": "nx:run-script",
             "inputs": ["source", "tests"],
             "options": {
                 "script": "test:integration"
             }
+        },
+        "test:boost-recipients": {
+            "executor": "nx:run-script",
+            "cache": false,
+            "dependsOn": ["^build"],
+            "inputs": ["source", "tests", "{projectRoot}/vitest.boost-recipients-neo4j.config.ts"],
+            "options": {
+                "script": "test:boost-recipients"
+            }
         }
     }
 }

package/scripts/backfill-profile-search.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env bun
+/**
+ * Backfills `Profile.displayNameLower`, the normalized copy of `displayName` (see
+ * `normalizeProfileSearchText`) that case-insensitive profile search reads through the
+ * `profile_displayname_lower_text_idx` TEXT index.
+ *
+ * New and updated profiles get the field on write. Run this once per environment after the
+ * release that adds or changes it, and only once no instance of the previous build is still
+ * writing profiles, so profiles written before then are findable by display name again.
+ * It's idempotent and only touches profiles whose copy is missing or out of date.
+ *
+ * Usage (from services/learn-card-network/brain-service):
+ *   NEO4J_URI=... NEO4J_USERNAME=... NEO4J_PASSWORD=... \
+ *     bun run backfill:profile-search -- --yes [--batch-size 1000]
+ *
+ * Without --yes it only counts the profiles that need the field and changes nothing.
+ */
+
+import neo4j from 'neo4j-driver';
+
+import {
+    PROFILE_DISPLAY_NAME_LOWER_FIELD,
+    backfillProfileDisplayNameLower,
+    buildBackfillProfileDisplayNameLowerQuery,
+    profileDisplayNameLowerIsStale,
+} from '../src/accesslayer/profile/search-fields';
+
+const getArg = (name: string): string | undefined => {
+    const index = process.argv.indexOf(name);
+    return index === -1 ? undefined : process.argv[index + 1];
+};
+
+const main = async (): Promise<void> => {
+    const uri = process.env.NEO4J_URI;
+    const username = process.env.NEO4J_USERNAME;
+    const password = process.env.NEO4J_PASSWORD;
+
+    if (!uri || !username || !password) {
+        throw new Error('NEO4J_URI, NEO4J_USERNAME and NEO4J_PASSWORD must all be set explicitly.');
+    }
+
+    const write = process.argv.includes('--yes');
+    const batchSize = Number(getArg('--batch-size') ?? 1000);
+
+    console.log(`Target: ${uri} (${write ? 'write' : 'dry run, pass --yes to write'})`);
+
+    const driver = neo4j.driver(uri, neo4j.auth.basic(username, password));
+    const session = driver.session();
+
+    try {
+        if (!write) {
+            const result = await session.run(
+                `MATCH (profile:Profile)
+                 WHERE ${profileDisplayNameLowerIsStale('profile')}
+                 RETURN count(profile) AS pending`
+            );
+            console.log(
+                `Profiles needing ${PROFILE_DISPLAY_NAME_LOWER_FIELD}:`,
+                result.records[0]?.get('pending').toString()
+            );
+            console.log(`Would run:\n${buildBackfillProfileDisplayNameLowerQuery(batchSize)}`);
+            return;
+        }
+
+        const updated = await backfillProfileDisplayNameLower(query => session.run(query), {
+            batchSize,
+        });
+
+        console.log(`Set ${PROFILE_DISPLAY_NAME_LOWER_FIELD} on ${updated} profiles.`);
+    } finally {
+        await session.close();
+        await driver.close();
+    }
+};
+
+main().catch(error => {
+    console.error(error);
+    process.exit(1);
+});

package/scripts/seed-demo-persona.ts

@@ -33,6 +33,10 @@ import {
 } from '@learncard/credential-library';
 import type { UnsignedVC } from '@learncard/types';
 import { flattenObject } from '../src/helpers/objects.helpers';
+import {
+    PROFILE_DISPLAY_NAME_LOWER_FIELD,
+    normalizeProfileSearchText,
+} from '../src/accesslayer/profile/search-fields';
 
 dotenv.config({ path: fileURLToPath(new URL('../.env', import.meta.url)) });
 
@@ -237,7 +241,8 @@ const main = async (): Promise<void> => {
                  SET p.displayName = $displayName,
                      p.shortBio = $shortBio,
                      p.image = $image,
-                     p.did = $did
+                     p.did = $did,
+                     p.${PROFILE_DISPLAY_NAME_LOWER_FIELD} = ${normalizeProfileSearchText('$displayName')}
                  RETURN p.did AS did`,
                 {
                     profileId: issuer.profileId,

package/src/accesslayer/boost/read.ts

@@ -259,6 +259,159 @@ export const countBoostSiblings = async (
     return Number(result.records[0]?.get('count') ?? 0);
 };
 
+/**
+ * Builds the Cypher (to follow `MATCH (start:Boost { id })`) that binds `boost` to every distinct
+ * member of start's family: ancestors (up to parentGenerations), descendants (up to
+ * childGenerations) and siblings (or, with includeExtendedFamily, cousins), never start itself
+ * via the sibling path.
+ *
+ * Each branch is expanded outward from the already-bound `start` node, so the cost is proportional
+ * to the size of the family. The previous form (`MATCH (boost:Boost) WHERE <pattern> OR <pattern>`)
+ * label-scanned every Boost node and evaluated the pattern predicates per node.
+ *
+ * Generations are interpolated (Cypher cannot parameterise variable-length bounds); callers must
+ * validate they are numbers. Non-finite values produce an unbounded range, matching prior behaviour.
+ */
+const getFamilialBoostsCypher = ({
+    parentGenerations,
+    childGenerations,
+    includeExtendedFamily,
+}: {
+    parentGenerations: number;
+    childGenerations: number;
+    includeExtendedFamily: boolean;
+}): string => {
+    const parentRange = Number.isFinite(parentGenerations) ? parentGenerations : '';
+    const childRange = Number.isFinite(childGenerations) ? childGenerations : '';
+    const siblingParentHops = includeExtendedFamily ? `*1..${parentRange}` : '';
+    const siblingChildHops = includeExtendedFamily ? `*1..${childRange}` : '';
+
+    return `
+OPTIONAL MATCH (start)<-[:PARENT_OF*1..${parentRange}]-(ancestor:Boost)
+WITH start, COLLECT(DISTINCT ancestor) AS ancestors
+OPTIONAL MATCH (start)-[:PARENT_OF*1..${childRange}]->(descendant:Boost)
+WITH start, ancestors, COLLECT(DISTINCT descendant) AS descendants
+OPTIONAL MATCH (start)<-[:PARENT_OF${siblingParentHops}]-(:Boost)-[:PARENT_OF${siblingChildHops}]->(sibling:Boost)
+WHERE sibling <> start
+WITH ancestors, descendants, COLLECT(DISTINCT sibling) AS siblings
+UNWIND ancestors + descendants + siblings AS boost
+WITH DISTINCT boost`;
+};
+
+/**
+ * Above this many index candidates, `getFamilialBoostsByCandidatesCypher` falls back to expanding
+ * the family. At or below it, checking each candidate is cheaper than walking a wide family.
+ */
+const FAMILIAL_CANDIDATE_LIMIT = 16;
+
+/** Boost properties with a range index (see models/index.ts) */
+const INDEXED_BOOST_FIELDS = ['id', 'category', 'autoConnectRecipients'] as const;
+
+/**
+ * Finds one top-level condition in a converted BoostQuery that Neo4j can answer from an index:
+ * plain equality or `$in` on an indexed Boost property. buildWhereClause ANDs top-level fields
+ * together, so every boost the full filter accepts also passes this condition.
+ *
+ * The value is bound as `$familialProbe`, which can't clash with buildWhereClause's `param_N`.
+ */
+const getIndexedFamilialProbe = (
+    query: Record<string, unknown>
+): { predicate: string; value: unknown } | undefined => {
+    // A document-level $or makes buildWhereClause ignore the other top-level keys
+    if ('$or' in query) return undefined;
+
+    for (const field of INDEXED_BOOST_FIELDS) {
+        const value = query[field];
+
+        if (value === undefined) continue;
+
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return { predicate: `c.${field} = $familialProbe`, value };
+        }
+
+        // Mirrors buildFieldCondition: a field-level $or wins over $in, then $in wins over the rest
+        if (!('$or' in value) && '$in' in value && Array.isArray(value.$in)) {
+            return { predicate: `c.${field} IN $familialProbe`, value: value.$in };
+        }
+    }
+
+    return undefined;
+};
+
+/**
+ * Same contract as `getFamilialBoostsCypher`, for queries with an indexed filter.
+ *
+ * It first index-seeks up to FAMILIAL_CANDIDATE_LIMIT + 1 boosts that pass the indexed condition.
+ * - More than the limit: the family is expanded exactly as in `getFamilialBoostsCypher`.
+ * - Otherwise: only those candidates are checked. A candidate is an ancestor if it is in start's
+ *   ancestors, a descendant if start is among its own ancestors (walked up from the candidate,
+ *   which stays small even under a wide parent), and a sibling via the original pattern.
+ *
+ * With includeExtendedFamily, the cousin check intersects the candidate's ancestors with start's.
+ * That set check can also reach nodes the single-pattern form can't (it ignores relationship
+ * uniqueness across the up and down legs), but any such node is already an ancestor or
+ * descendant of start as long as every node above start is a Boost. When a non-Boost node sits
+ * above start, the original cousin pattern is used instead.
+ */
+const getFamilialBoostsByCandidatesCypher = ({
+    parentGenerations,
+    childGenerations,
+    includeExtendedFamily,
+    probe,
+}: {
+    parentGenerations: number;
+    childGenerations: number;
+    includeExtendedFamily: boolean;
+    probe: string;
+}): string => {
+    const p = Number.isFinite(parentGenerations) ? parentGenerations : '';
+    const c = Number.isFinite(childGenerations) ? childGenerations : '';
+    const up = includeExtendedFamily ? `*1..${p}` : '';
+    const down = includeExtendedFamily ? `*1..${c}` : '';
+    const k = FAMILIAL_CANDIDATE_LIMIT;
+    const sibling = includeExtendedFamily
+        ? `(n=size(a) AND any(x IN bu WHERE x IN a) OR n<>size(a) AND EXISTS{(start)<-[:PARENT_OF${up}]-(:Boost)-[:PARENT_OF${down}]->(boost)})`
+        : 'EXISTS{(start)<-[:PARENT_OF]-(:Boost)-[:PARENT_OF]->(boost)}';
+
+    return `
+CALL{MATCH(c:Boost)WHERE ${probe} WITH c LIMIT ${k + 1} RETURN collect(c)AS cs}
+OPTIONAL MATCH(start)<-[:PARENT_OF*1..${p}]-(u)
+WITH start,cs,collect(DISTINCT u)AS us
+WITH start,cs,size(us)AS n,[x IN us WHERE x:Boost]AS a
+CALL{WITH start,cs WITH start WHERE size(cs)>${k}
+OPTIONAL MATCH(start)-[:PARENT_OF*1..${c}]->(d:Boost)RETURN collect(DISTINCT d)AS ds}
+CALL{WITH start,cs WITH start WHERE size(cs)>${k}
+OPTIONAL MATCH(start)<-[:PARENT_OF${up}]-(:Boost)-[:PARENT_OF${down}]->(s:Boost)WHERE s<>start
+RETURN collect(DISTINCT s)AS ss}
+CALL{WITH start,cs,n,a WITH * WHERE size(cs)<=${k}
+UNWIND cs AS boost
+OPTIONAL MATCH(boost)<-[:PARENT_OF*1..${c}]-(v)
+WITH start,n,a,boost,collect(DISTINCT v)AS bu
+WHERE boost IN a OR start IN bu OR boost<>start AND ${sibling}
+RETURN collect(boost)AS hits}
+UNWIND CASE WHEN size(cs)>${k} THEN a+ds+ss ELSE hits END AS boost
+WITH DISTINCT boost`;
+};
+
+/** Picks the familial Cypher for a query and returns the extra params it needs */
+const getFamilialCypherForQuery = (
+    query: Record<string, unknown>,
+    generations: {
+        parentGenerations: number;
+        childGenerations: number;
+        includeExtendedFamily: boolean;
+    }
+): { cypher: string; params: Record<string, unknown> } => {
+    const probe = getIndexedFamilialProbe(query);
+
+    if (!probe) return { cypher: getFamilialBoostsCypher(generations), params: {} };
+
+    return {
+        cypher: getFamilialBoostsByCandidatesCypher({ ...generations, probe: probe.predicate }),
+        params: { familialProbe: probe.value },
+    };
+};
+
 export const getFamilialBoosts = async (
     boost: BoostInstance,
     {
@@ -291,24 +444,16 @@ export const getFamilialBoosts = async (
         convertedQuery as any
     );
 
-    const _query = new QueryBuilder(new BindParam({ cursor, ...queryParams }))
+    const familial = getFamilialCypherForQuery(convertedQuery, {
+        parentGenerations,
+        childGenerations,
+        includeExtendedFamily,
+    });
+
+    const _query = new QueryBuilder(new BindParam({ cursor, ...queryParams, ...familial.params }))
         .match({ model: Boost, where: { id: boost.id }, identifier: 'start' })
-        .match({ model: Boost, identifier: 'boost' })
-        .where(
-            `
-((start)<-[:PARENT_OF*1..${Number.isFinite(parentGenerations) ? parentGenerations : ''}]-(boost) OR 
-(start)-[:PARENT_OF*1..${Number.isFinite(childGenerations) ? childGenerations : ''}]->(boost) OR 
-(start)<-[:PARENT_OF${
-                includeExtendedFamily
-                    ? `*1..${Number.isFinite(parentGenerations) ? parentGenerations : ''}`
-                    : ''
-            }]-(:Boost)-[:PARENT_OF${
-                includeExtendedFamily
-                    ? `*1..${Number.isFinite(childGenerations) ? childGenerations : ''}`
-                    : ''
-            }]->(boost) AND boost <> start)
-AND ${whereClause}`
-        )
+        .raw(familial.cypher)
+        .where(whereClause)
         .raw(`MATCH (boost)-[createdBy:${Boost.getRelationshipByAlias('createdBy').name}]-()`);
 
     const query = cursor ? _query.where('createdBy.date < $cursor') : _query;
@@ -358,24 +503,16 @@ export const countFamilialBoosts = async (
         convertedQuery as any
     );
 
-    const query = new QueryBuilder(new BindParam({ ...queryParams }))
+    const familial = getFamilialCypherForQuery(convertedQuery, {
+        parentGenerations,
+        childGenerations,
+        includeExtendedFamily,
+    });
+
+    const query = new QueryBuilder(new BindParam({ ...queryParams, ...familial.params }))
         .match({ model: Boost, where: { id: boost.id }, identifier: 'start' })
-        .match({ model: Boost, identifier: 'boost' })
-        .where(
-            `
-((start)<-[:PARENT_OF*1..${Number.isFinite(parentGenerations) ? parentGenerations : ''}]-(boost) OR 
-(start)-[:PARENT_OF*1..${Number.isFinite(childGenerations) ? childGenerations : ''}]->(boost) OR 
-(start)<-[:PARENT_OF${
-                includeExtendedFamily
-                    ? `*1..${Number.isFinite(parentGenerations) ? parentGenerations : ''}`
-                    : ''
-            }]-(:Boost)-[:PARENT_OF${
-                includeExtendedFamily
-                    ? `*1..${Number.isFinite(childGenerations) ? childGenerations : ''}`
-                    : ''
-            }]->(boost) AND boost <> start)
-AND ${whereClause}`
-        );
+        .raw(familial.cypher)
+        .where(whereClause);
 
     const result = await query.return('COUNT(DISTINCT boost) AS count').run();