@learncard/network-brain-service 4.0.3 → 4.1.0

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/routes/workflows.ts

@@ -37,7 +37,12 @@ import { createClaimedRelationship } from '@accesslayer/inbox-credential/relatio
 import { getContactMethodById, getProfileByContactMethod } from '@accesslayer/contact-method/read';
 import { getProfileByDid, getProfileByProfileId } from '@accesslayer/profile/read';
 
-import { getBoostUri, isBoostViewableByClaimLink, isDraftBoost } from '@helpers/boost.helpers';
+import {
+    getBoostUri,
+    isBoostViewableByClaimLink,
+    isDraftBoost,
+    stampIssuanceDate,
+} from '@helpers/boost.helpers';
 import { getBoostOwnerProfile } from 'types/boost';
 import { getEmptyLearnCard, getLearnCard } from '@helpers/learnCard.helpers';
 import { issueCredentialWithSigningAuthority } from '@helpers/signingAuthority.helpers';
@@ -392,6 +397,8 @@ async function handlePresentationForClaim(
 
         boostCredential.issuer = signingAuthorityForUser.relationship.did;
 
+        stampIssuanceDate(boostCredential);
+
         if (Array.isArray(boostCredential.credentialSubject)) {
             boostCredential.credentialSubject = boostCredential.credentialSubject.map(subject => ({
                 ...subject,

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[];
 };