@learncard/network-brain-service 4.0.4 → 4.1.1

package/src/routes/skills.ts

@@ -22,10 +22,14 @@ import {
 import { createSkill } from '@accesslayer/skill/create';
 import { updateSkill, deleteSkill } from '@accesslayer/skill/update';
 import {
-    generateEmbeddingForText,
-    getCachedEmbeddingForText,
+    generateQueryEmbedding,
+    getCachedQueryEmbedding,
+    getSkillEmbeddingSearchIndex,
+    isSkillEmbeddingNovaReadEnabled,
+    isSkillEmbeddingError,
     upsertSkillEmbeddings,
 } from '@helpers/skill-embedding.helpers';
+import { NOVA2_MAX_TEXT_CHARS } from '../config/skillEmbedding';
 import { listTagsForSkill, addTagToSkill, removeTagFromSkill } from '@accesslayer/skill/tags';
 import {
     TagValidator,
@@ -226,7 +230,16 @@ export const skillsRouter = t.router({
         .query(async ({ ctx, input }) => {
             const profileId = ctx.user.profile.profileId;
             const { text, frameworkId, limit } = input;
-            const cachedEmbedding = await getCachedEmbeddingForText(text);
+
+            // Nova's synchronous input limit; the legacy Google read path keeps main's behaviour.
+            if (isSkillEmbeddingNovaReadEnabled() && text.trim().length > NOVA2_MAX_TEXT_CHARS) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: `Semantic search text must be at most ${NOVA2_MAX_TEXT_CHARS} characters`,
+                });
+            }
+
+            const cachedEmbedding = await getCachedQueryEmbedding(text);
 
             if (!cachedEmbedding) {
                 const rateLimitKey = `skill-semantic-search-rate:${profileId}`;
@@ -249,16 +262,39 @@ export const skillsRouter = t.router({
 
             let embedding: number[];
             try {
-                embedding = cachedEmbedding ?? (await generateEmbeddingForText(text));
+                embedding = cachedEmbedding ?? (await generateQueryEmbedding(text));
             } catch (error) {
-                console.error('Failed to generate embedding for skill search:', error);
+                const code = isSkillEmbeddingError(error) ? error.code : 'failed';
+                console.error(`Failed to generate embedding for skill search: ${code}`);
+
+                if (code === 'throttled') {
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message: 'Skill search is rate limited. Please try again shortly.',
+                    });
+                }
+
+                if (code === 'unavailable' || code === 'timeout' || code === 'disabled') {
+                    throw new TRPCError({
+                        code: 'SERVICE_UNAVAILABLE',
+                        message: 'Skill search is temporarily unavailable',
+                    });
+                }
+
                 throw new TRPCError({
                     code: 'INTERNAL_SERVER_ERROR',
                     message: 'Failed to generate embedding for skill search',
                 });
             }
 
-            const results = await searchSkillsByEmbedding(embedding, limit, frameworkId);
+            // Legacy Google index unless SKILL_EMBEDDING_BEDROCK_READ_ENABLED (LC-2206); the query
+            // embedding above was produced for the same index.
+            const results = await searchSkillsByEmbedding(
+                embedding,
+                limit,
+                frameworkId,
+                getSkillEmbeddingSearchIndex()
+            );
 
             return {
                 records: results.map(({ skill, score }) => ({

package/src/seed/seedSkillFrameworks.embeddings.test.ts

@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DEFAULT_SKILL_FRAMEWORKS } from './skill-frameworks.fixtures';
+
+// Review r4339891853: a failing Nova pass must not suppress the legacy Google pass (and the
+// reverse), and each failure must still be reported. Bedrock and Google are mocked here.
+const embeddings = vi.hoisted(() => ({
+    upsertNova: vi.fn(),
+    upsertLegacy: vi.fn(),
+}));
+
+class FakeSkillEmbeddingError extends Error {
+    constructor(readonly code: string) {
+        super(code);
+    }
+}
+
+vi.mock('@helpers/skill-embedding.helpers', () => ({
+    upsertNovaSkillEmbeddings: embeddings.upsertNova,
+    upsertLegacySkillEmbeddings: embeddings.upsertLegacy,
+    isSkillEmbeddingEnabled: () => true,
+    isLegacySkillEmbeddingEnabled: () => true,
+    isSkillEmbeddingError: (error: unknown) => error instanceof FakeSkillEmbeddingError,
+    getSkillEmbeddingGeneration: () => ({ vectorProperty: 'embedding_nova2_v1_0_d1024' }),
+}));
+
+/** Query runner double: every framework has one skill missing both vectors. */
+const run = vi.fn(async (query: string, params?: Record<string, unknown>) => {
+    if (query.includes('IS NULL') && query.includes('[:CONTAINS]->(s:Skill)')) {
+        const frameworkId = String(params?.frameworkId);
+        return {
+            records: [
+                {
+                    get: (key: string) =>
+                        key === 's'
+                            ? { properties: { id: `${frameworkId}-skill`, statement: 'Python' } }
+                            : null,
+                },
+            ],
+        };
+    }
+    return { records: [] };
+});
+
+describe('seedSkillFrameworkFixtures embedding passes', () => {
+    beforeEach(() => {
+        run.mockClear();
+        embeddings.upsertNova.mockReset();
+        embeddings.upsertLegacy.mockReset().mockResolvedValue(undefined);
+    });
+
+    it('still writes legacy embeddings for every framework when Nova is denied, and reports it', async () => {
+        embeddings.upsertNova.mockRejectedValue(new FakeSkillEmbeddingError('access_denied'));
+        const log = { log: vi.fn(), warn: vi.fn() };
+        const { seedSkillFrameworkFixtures } = await import('./seedSkillFrameworks');
+
+        await seedSkillFrameworkFixtures(run, { log });
+
+        expect(embeddings.upsertLegacy).toHaveBeenCalledTimes(DEFAULT_SKILL_FRAMEWORKS.length);
+        // Nova stops after its first failure instead of retrying every framework.
+        expect(embeddings.upsertNova).toHaveBeenCalledTimes(1);
+        const warnings = log.warn.mock.calls.map(call => String(call[0])).join('\n');
+        expect(warnings).toContain('Nova');
+        expect(warnings).toContain('Bedrock denied the embedding request');
+        expect(warnings).not.toMatch(/legacy google embedding backfill was skipped/i);
+    });
+
+    it('still writes Nova embeddings when the legacy Google pass fails, and reports it', async () => {
+        embeddings.upsertNova.mockResolvedValue(undefined);
+        embeddings.upsertLegacy.mockRejectedValue(new Error('google down'));
+        const log = { log: vi.fn(), warn: vi.fn() };
+        const { seedSkillFrameworkFixtures } = await import('./seedSkillFrameworks');
+
+        await seedSkillFrameworkFixtures(run, { log });
+
+        expect(embeddings.upsertNova).toHaveBeenCalledTimes(DEFAULT_SKILL_FRAMEWORKS.length);
+        expect(embeddings.upsertLegacy).toHaveBeenCalledTimes(1);
+        const warnings = log.warn.mock.calls.map(call => String(call[0])).join('\n');
+        expect(warnings).toMatch(/legacy google embedding backfill was skipped/i);
+        expect(warnings).not.toMatch(/nova embedding backfill was skipped/i);
+    });
+});

package/src/seed/seedSkillFrameworks.test.ts

@@ -24,6 +24,12 @@ vi.mock('neogma', () => ({
 }));
 vi.mock('@helpers/skill-embedding.helpers', () => ({
     upsertSkillEmbeddings: mockUpsertSkillEmbeddings,
+    upsertNovaSkillEmbeddings: mockUpsertSkillEmbeddings,
+    upsertLegacySkillEmbeddings: mockUpsertSkillEmbeddings,
+    isSkillEmbeddingEnabled: () => false,
+    isLegacySkillEmbeddingEnabled: () => false,
+    isSkillEmbeddingError: () => false,
+    getSkillEmbeddingGeneration: vi.fn(),
 }));
 
 describe('seedSkillFrameworks staging env resolution', () => {

package/src/seed/seedSkillFrameworks.ts

@@ -10,9 +10,20 @@ import {
     type SeedSkillNode,
 } from './skill-frameworks.fixtures';
 import {
-    upsertSkillEmbeddings,
+    getSkillEmbeddingGeneration,
+    isLegacySkillEmbeddingEnabled,
+    isSkillEmbeddingEnabled,
+    isSkillEmbeddingError,
+    upsertLegacySkillEmbeddings,
+    upsertNovaSkillEmbeddings,
+    type UpdateLegacySkillEmbeddingFn,
     type UpdateSkillEmbeddingFn,
 } from '@helpers/skill-embedding.helpers';
+import {
+    LEGACY_GOOGLE_SKILL_EMBEDDING_PROPERTY,
+    buildSkillEmbeddingUpdateParams,
+    buildSkillEmbeddingUpdateQuery,
+} from '../config/skillEmbedding';
 import { syncProfileDisplayNameLower } from '../accesslayer/profile/search-fields';
 
 // Inlined from @helpers/profile.helpers to avoid importing the access/model layer
@@ -365,6 +376,20 @@ export const addSkillFrameworkAdmin = async (
 };
 
 const buildSeedSkillEmbeddingUpdater = (run: QueryRunnerLike['run']): UpdateSkillEmbeddingFn => {
+    return async update => {
+        const result = await run(
+            buildSkillEmbeddingUpdateQuery(update.generation, Boolean(update.frameworkId)),
+            buildSkillEmbeddingUpdateParams(update)
+        );
+
+        return Number(result.records[0]?.get('count') ?? 0) > 0;
+    };
+};
+
+/** LC-2206 legacy write (main's Cypher), kept while search can still read the legacy index. */
+const buildSeedLegacySkillEmbeddingUpdater = (
+    run: QueryRunnerLike['run']
+): UpdateLegacySkillEmbeddingFn => {
     return async (skillId, embedding, frameworkId) => {
         if (frameworkId) {
             const result = await run(
@@ -390,7 +415,8 @@ const buildSeedSkillEmbeddingUpdater = (run: QueryRunnerLike['run']): UpdateSkil
 
 const getSeedSkillsMissingEmbedding = async (
     run: QueryRunnerLike['run'],
-    frameworkId: string
+    frameworkId: string,
+    vectorProperty: string
 ): Promise<
     Array<{
         id: string;
@@ -400,9 +426,10 @@ const getSeedSkillsMissingEmbedding = async (
         code?: string;
     }>
 > => {
+    // Property names come from resolveSkillEmbeddingGeneration or the legacy constant ([a-z0-9_] only).
     const result = await run(
         `MATCH (f:SkillFramework {id: $frameworkId})-[:CONTAINS]->(s:Skill)
-         WHERE s.embedding IS NULL
+         WHERE s.${vectorProperty} IS NULL
          OPTIONAL MATCH (s)-[:IS_CHILD_OF]->(parent:Skill)
          RETURN s AS s, parent.id AS parentId
          ORDER BY s.id`,
@@ -423,19 +450,18 @@ const getSeedSkillsMissingEmbedding = async (
     });
 };
 
-const describeEmbeddingBackfillFailure = (error: unknown): string => {
-    const message = error instanceof Error ? error.message : String(error);
-    const normalized = message.toLowerCase();
+export const describeEmbeddingBackfillFailure = (error: unknown): string => {
+    const code = isSkillEmbeddingError(error) ? error.code : undefined;
 
-    if (normalized.includes('quota exceeded') || normalized.includes('resource_exhausted')) {
-        return '\nEmbedding quota was reached. \nThe frameworks were seeded, but semantic search will stay limited until the Google embedding quota resets or you switch to a paid key.\n';
+    if (code === 'throttled') {
+        return 'Bedrock embedding requests were throttled. The frameworks were seeded, but some semantic search embeddings were skipped for now; the startup backfill will fill them in.';
     }
 
-    if (normalized.includes('rate limits') || normalized.includes('too many requests')) {
-        return 'Google embedding requests were rate-limited. The frameworks were seeded, but some semantic search embeddings were skipped for now.';
+    if (code === 'access_denied') {
+        return 'Bedrock denied the embedding request. Check model access for Nova 2 Multimodal Embeddings and the bedrock:InvokeModel grant for your AWS credentials.';
     }
 
-    return `${message}\nUse \`bun run skill-frameworks add-admin\` to add admins.`;
+    return `Skill embedding failed (${code ?? 'unknown'}).\nUse \`bun run skill-frameworks add-admin\` to add admins.`;
 };
 
 const upsertSkillNode = async (
@@ -547,7 +573,12 @@ export const seedSkillFrameworkFixtures = async (
     await ensureSeedProfile(run, ownerProfileId);
 
     const seededFrameworkIds: string[] = [];
-    let embeddingBackfillFailureSummary: string | null = null;
+    // Each provider tracks its own failure, so a Nova failure never skips the legacy Google
+    // pass that semantic search may still be reading (and vice versa).
+    const embeddingFailures: { nova: string | null; legacy: string | null } = {
+        nova: null,
+        legacy: null,
+    };
 
     for (const framework of fixtures) {
         const now = new Date().toISOString();
@@ -592,17 +623,42 @@ export const seedSkillFrameworkFixtures = async (
             await upsertSkillNode(run, framework, rootSkill);
         }
 
-        if (!embeddingBackfillFailureSummary) {
-            const missingEmbeddingSkills = await getSeedSkillsMissingEmbedding(run, framework.id);
+        // LC-2206: Nova vectors whenever Nova is enabled (independent of the read flag), plus
+        // the legacy Google vectors main writes while a Google key is configured.
+        if (!embeddingFailures.nova && isSkillEmbeddingEnabled()) {
+            const missingEmbeddingSkills = await getSeedSkillsMissingEmbedding(
+                run,
+                framework.id,
+                getSkillEmbeddingGeneration().vectorProperty
+            );
 
             if (missingEmbeddingSkills.length > 0) {
                 try {
-                    await upsertSkillEmbeddings(
+                    await upsertNovaSkillEmbeddings(
                         missingEmbeddingSkills,
                         buildSeedSkillEmbeddingUpdater(run)
                     );
                 } catch (error) {
-                    embeddingBackfillFailureSummary = describeEmbeddingBackfillFailure(error);
+                    embeddingFailures.nova = describeEmbeddingBackfillFailure(error);
+                }
+            }
+        }
+
+        if (!embeddingFailures.legacy && isLegacySkillEmbeddingEnabled()) {
+            const missingLegacySkills = await getSeedSkillsMissingEmbedding(
+                run,
+                framework.id,
+                LEGACY_GOOGLE_SKILL_EMBEDDING_PROPERTY
+            );
+
+            if (missingLegacySkills.length > 0) {
+                try {
+                    await upsertLegacySkillEmbeddings(
+                        missingLegacySkills,
+                        buildSeedLegacySkillEmbeddingUpdater(run)
+                    );
+                } catch (error) {
+                    embeddingFailures.legacy = describeEmbeddingBackfillFailure(error);
                 }
             }
         }
@@ -610,10 +666,19 @@ export const seedSkillFrameworkFixtures = async (
         seededFrameworkIds.push(framework.id);
     }
 
-    if (embeddingBackfillFailureSummary) {
+    if (embeddingFailures.nova) {
         options.log?.warn?.(
-            `Embedding backfill was skipped after the first framework because Google rejected the request: ${embeddingBackfillFailureSummary}`
+            `Nova embedding backfill was skipped for the remaining frameworks: ${embeddingFailures.nova}`
         );
+    }
+
+    if (embeddingFailures.legacy) {
+        options.log?.warn?.(
+            `Legacy Google embedding backfill was skipped for the remaining frameworks: ${embeddingFailures.legacy}`
+        );
+    }
+
+    if (embeddingFailures.nova || embeddingFailures.legacy) {
         options.log?.warn?.(
             'The frameworks were still seeded. Use `bun run skill-frameworks add-admin` to add admins. Semantic search will keep using whichever embeddings already exist.'
         );

package/src/types/campaign.ts

@@ -0,0 +1,17 @@
+import type { CampaignStatus } from '@learncard/types';
+
+export type CampaignRecord = {
+    id: string;
+    name: string;
+    status: CampaignStatus;
+    definition: string;
+    startsAt?: string;
+    endsAt?: string;
+    excludeMinors: boolean;
+    selfEnroll: boolean;
+    createdByProfileId: string;
+    createdAt: string;
+    updatedAt: string;
+};
+
+export type CampaignAudienceQuery = { match: string; params: Record<string, unknown> };

package/src/types/skill.ts

@@ -12,5 +12,11 @@ export const FlatSkillValidator = SkillValidator.extend({
 export type FlatSkillType = z.infer<typeof FlatSkillValidator>;
 
 export type SkillDbType = FlatSkillType & {
+    /**
+     * Legacy gemini-embedding-001 (768-d) vector. Still written on skill changes and read by
+     * semantic search until SKILL_EMBEDDING_BEDROCK_READ_ENABLED is on (LC-2206); dropped by the
+     * post-rollback-window cleanup. Nova 2 vectors live in generation-specific properties
+     * (see config/skillEmbedding.ts).
+     */
     embedding?: number[];
 };

package/test/app-credential-delivery.neo4j.spec.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { neogma } from '@instance';
+import { Boost } from '@models';
+import { sendAppCredentialWithActivity } from '@helpers/app-credential-delivery.helpers';
+import { getBoostUri } from '@helpers/boost.helpers';
+import type { CredentialIssuer } from '../src/types/issuer';
+
+const domain = 'localhost%3A3000';
+const issuer: CredentialIssuer = {
+    type: 'appStoreListing',
+    listing: { listing_id: 'race-listing', display_name: 'Race Test App' },
+    ownerProfile: { profileId: 'race-owner' },
+} as CredentialIssuer;
+const credential = {
+    protected: 'header',
+    iv: 'iv',
+    ciphertext: 'ciphertext',
+    tag: 'tag',
+    recipients: [],
+};
+
+// The integration and CI inbox configs both supply a fresh Testcontainers database.
+// No environment-configured development or deployed database is used.
+describe('app credential delivery graph (real Neo4j)', () => {
+    beforeEach(async () => {
+        await neogma.queryRunner.run('MATCH (n) DETACH DELETE n');
+        await neogma.queryRunner.run(`
+            CREATE (owner:Profile {profileId: 'race-owner'}),
+                   (learner:Profile {profileId: 'race-learner'}),
+                   (listing:AppStoreListing {listing_id: 'race-listing'}),
+                   (boost:Boost {id: 'race-boost'})
+            CREATE (owner)-[:PUBLISHED]->(listing), (listing)-[:HAS_BOOST]->(boost)
+        `);
+    });
+
+    const issue = async (sequence: number): Promise<string> => {
+        const boost = await Boost.findOne({ where: { id: 'race-boost' } });
+        if (!boost) throw new Error('Missing fixture boost');
+        return sendAppCredentialWithActivity(
+            {
+                actorProfileId: 'race-owner',
+                recipientType: 'profile',
+                recipientIdentifier: 'race-learner',
+                recipientProfileId: 'race-learner',
+                boostUri: getBoostUri(boost.id, domain),
+                integrationId: 'race-integration',
+                listingId: 'race-listing',
+                source: 'appEvent',
+                metadata: { sequence },
+            },
+            {
+                from: issuer,
+                to: { profileId: 'race-learner' },
+                boost,
+                credential,
+                domain,
+                skipNotification: true,
+                listingId: 'race-listing',
+                integrationId: 'race-integration',
+                metadata: { sequence },
+            }
+        );
+    };
+
+    const assertGraph = async (expected: number): Promise<void> => {
+        const { records } = await neogma.queryRunner.run(`
+            MATCH (c:Credential)
+            RETURN c.credential AS payload,
+                [(p:Profile)-[r:CREDENTIAL_SENT]->(c) | properties(r)] AS profileEdges,
+                [(l:AppStoreListing)-[r:CREDENTIAL_SENT]->(c) | properties(r)] AS listingEdges,
+                [(c)-[:INSTANCE_OF]->(b:Boost) | b.id] AS boosts
+        `);
+        expect(records).toHaveLength(expected);
+        for (const row of records) {
+            expect(JSON.parse(row.get('payload'))).toEqual(credential);
+            expect(row.get('profileEdges')).toHaveLength(1);
+            expect(row.get('listingEdges')).toHaveLength(1);
+            expect(row.get('boosts')).toEqual(['race-boost']);
+            const [edge] = row.get('listingEdges');
+            expect(edge.to).toBe('race-learner');
+            expect(edge.integrationId).toBe('race-integration');
+            expect(edge.activityId).toBe(row.get('profileEdges')[0].activityId);
+            const result = await neogma.queryRunner.run(
+                `
+                MATCH (:AppStoreListing {listing_id: 'race-listing'})-[:PERFORMED_BY_LISTING]->(a:CredentialActivity {activityId: $activityId})
+                MATCH (:Profile {profileId: 'race-owner'})-[:PERFORMED]->(a)
+                MATCH (a)-[:TO_RECIPIENT]->(:Profile {profileId: 'race-learner'})
+                MATCH (a)-[:FOR_BOOST]->(:Boost {id: 'race-boost'})
+                RETURN a.metadata AS metadata
+            `,
+                { activityId: edge.activityId }
+            );
+            expect(result.records).toHaveLength(1);
+            expect(JSON.parse(result.records[0].get('metadata')).sequence).toBe(
+                Number(edge['metadata.sequence'])
+            );
+        }
+    };
+
+    it('repeated sends create exactly one linked activity and each required delivery edge', async () => {
+        for (let i = 0; i < 30; i++) await issue(i);
+        await assertGraph(30);
+    });
+
+    it('independent simultaneous sends keep their own activity and attribution', async () => {
+        const uris = await Promise.all(Array.from({ length: 8 }, (_, i) => issue(i)));
+        expect(new Set(uris).size).toBe(8);
+        await assertGraph(8);
+    });
+});