@learncard/network-brain-service 4.0.4 → 4.1.1

package/src/models/Campaign.ts

@@ -0,0 +1,32 @@
+import { ModelFactory, type ModelRelatedNodesI, type NeogmaInstance } from 'neogma';
+
+import { neogma } from '@instance';
+import type { CampaignRecord } from 'types/campaign';
+import type { Profile, ProfileInstance } from './Profile';
+
+export type CampaignRelationships = {
+    audience: ModelRelatedNodesI<typeof Profile, ProfileInstance>;
+    state: ModelRelatedNodesI<typeof Profile, ProfileInstance>;
+};
+export type CampaignInstance = NeogmaInstance<CampaignRecord, CampaignRelationships>;
+
+export const Campaign = ModelFactory<CampaignRecord, CampaignRelationships>(
+    {
+        label: 'Campaign',
+        primaryKeyField: 'id',
+        schema: {
+            id: { type: 'string', required: true },
+            name: { type: 'string', required: true },
+            status: { type: 'string', required: true },
+            definition: { type: 'string', required: true },
+            startsAt: { type: 'string', required: false },
+            endsAt: { type: 'string', required: false },
+            excludeMinors: { type: 'boolean', required: true },
+            selfEnroll: { type: 'boolean', required: true },
+            createdByProfileId: { type: 'string', required: true },
+            createdAt: { type: 'string', required: true },
+            updatedAt: { type: 'string', required: true },
+        },
+    },
+    neogma
+);

package/src/models/CredentialSharePreview.ts

@@ -0,0 +1,30 @@
+import { ModelFactory, NeogmaInstance } from 'neogma';
+import { neogma } from '@instance';
+
+type Properties = {
+    id: string;
+    name: string;
+    issuer: string;
+    shareUri: string;
+    createdAt: string;
+    updatedAt: string;
+    image?: string;
+};
+export type CredentialSharePreviewInstance = NeogmaInstance<Properties, Record<string, never>>;
+
+export const CredentialSharePreview = ModelFactory<Properties, Record<string, never>>(
+    {
+        label: 'CredentialSharePreview',
+        primaryKeyField: 'id',
+        schema: {
+            id: { type: 'string', required: true },
+            name: { type: 'string', required: true },
+            issuer: { type: 'string', required: true },
+            shareUri: { type: 'string', required: true },
+            createdAt: { type: 'string', required: true },
+            updatedAt: { type: 'string', required: true },
+            image: { type: 'string', required: false },
+        },
+    },
+    neogma
+);

package/src/models/Profile.ts

@@ -120,6 +120,7 @@ export const Profile: any = ModelFactory<FlatProfileType, ProfileRelationships>(
             image: { type: 'string', required: false },
             heroImage: { type: 'string', required: false },
             websiteLink: { type: 'string', required: false },
+            linkedInOrganizationId: { type: 'string', required: false },
             isServiceProfile: { type: 'boolean', required: false },
             type: { type: 'string', required: false },
             notificationsWebhook: { type: 'string', required: false },

package/src/models/campaign-constraints.ts

@@ -0,0 +1,22 @@
+import { neogma } from '@instance';
+
+let readiness: Promise<void> | undefined;
+
+/** Await uniqueness before accepting creates, even during concurrent cold starts. */
+export const ensureCampaignConstraints = (): Promise<void> => {
+    readiness ??= neogma.queryRunner
+        .run(
+            'CREATE CONSTRAINT campaign_id_unique IF NOT EXISTS FOR (c:Campaign) REQUIRE c.id IS UNIQUE'
+        )
+        .then(() => undefined)
+        .catch((error: unknown) => {
+            if (
+                (error as { code?: string })?.code ===
+                'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists'
+            )
+                return;
+            readiness = undefined;
+            throw error;
+        });
+    return readiness;
+};

package/src/models/index.ts

@@ -1,6 +1,11 @@
 import { environment } from '@environment';
 import { neogma } from '@instance';
 import { contractEventMaintenanceSchema } from '@helpers/contract-event-maintenance.helpers';
+import {
+    LEGACY_GOOGLE_SKILL_EMBEDDING_VECTOR_INDEX_QUERY,
+    buildSkillEmbeddingVectorIndexQuery,
+    resolveSkillEmbeddingGeneration,
+} from '../config/skillEmbedding';
 
 import { Boost } from './Boost';
 import { Profile } from './Profile';
@@ -17,6 +22,7 @@ import { CredentialActivity } from './CredentialActivity';
 import { CredentialRefresh } from './CredentialRefresh';
 import { StatusList } from './StatusList';
 import { ContactMethod } from './ContactMethod';
+import { Campaign } from './Campaign';
 import { ensureCredentialRefreshConstraints } from './credential-refresh-constraints';
 
 // Ensure CredentialActivity model is registered by referencing it
@@ -139,14 +145,22 @@ ContactMethod.addRelationships({
     profile: { model: Profile, direction: 'in', name: 'HAS_CONTACT_METHOD' },
 });
 
+Campaign.addRelationships({
+    audience: { model: Profile, direction: 'in', name: 'IN_CAMPAIGN_AUDIENCE' },
+    state: { model: Profile, direction: 'in', name: 'CAMPAIGN_STATE' },
+});
+
 const shouldCreateIndices =
     environment.NODE_ENV === 'production' || !environment.NEO4J_SKIP_INDICES;
 
 const indexQueries = [
+    'CREATE CONSTRAINT campaign_id_unique IF NOT EXISTS FOR (c:Campaign) REQUIRE c.id IS UNIQUE',
+    'CREATE INDEX campaign_status_idx IF NOT EXISTS FOR (c:Campaign) ON (c.status)',
     'CREATE CONSTRAINT consent_event_id IF NOT EXISTS FOR (e:ConsentFlowEvent) REQUIRE e.id IS UNIQUE',
     'CREATE CONSTRAINT consent_delivery_id IF NOT EXISTS FOR (d:ConsentFlowEventDelivery) REQUIRE d.id IS UNIQUE',
     ...contractEventMaintenanceSchema,
     'CREATE INDEX profileId_idx IF NOT EXISTS FOR (p:Profile) ON (p.profileId)',
+    'CREATE CONSTRAINT credential_share_preview_id_unique IF NOT EXISTS FOR (p:CredentialSharePreview) REQUIRE p.id IS UNIQUE',
     'CREATE INDEX profile_did_idx IF NOT EXISTS FOR (p:Profile) ON (p.did)',
     'CREATE TEXT INDEX profileId_text_idx IF NOT EXISTS FOR (n:Profile) ON (n.profileId)',
     'CREATE TEXT INDEX profile_displayname_text_idx IF NOT EXISTS FOR (n:Profile) ON (n.displayName)',
@@ -180,7 +194,19 @@ const indexQueries = [
     'CREATE TEXT INDEX skill_framework_name_text_idx IF NOT EXISTS FOR (f:SkillFramework) ON (f.name)',
     'CREATE INDEX skill_id_idx IF NOT EXISTS FOR (s:Skill) ON (s.id)',
     'CREATE TEXT INDEX skill_statement_text_idx IF NOT EXISTS FOR (s:Skill) ON (s.statement)',
-    "CREATE VECTOR INDEX skill_embedding_vector_idx IF NOT EXISTS FOR (s:Skill) ON (s.embedding) OPTIONS {indexConfig: {`vector.dimensions`: 768, `vector.similarity_function`: 'cosine'}}",
+    // LC-2206: the legacy Google 768-dim index (main's DDL, unchanged) stays because semantic
+    // search reads it until SKILL_EMBEDDING_BEDROCK_READ_ENABLED is on, and flipping the flag
+    // back off is the rollback. The post-rollback-window cleanup drops it.
+    LEGACY_GOOGLE_SKILL_EMBEDDING_VECTOR_INDEX_QUERY,
+    // One vector index per Nova embedding generation (1024 dims by default), written regardless
+    // of the read flag.
+    buildSkillEmbeddingVectorIndexQuery(
+        resolveSkillEmbeddingGeneration({
+            modelId: environment.SKILL_EMBEDDING_BEDROCK_MODEL_ID,
+            dimension: environment.SKILL_EMBEDDING_DIMENSION,
+            region: environment.SKILL_EMBEDDING_BEDROCK_REGION,
+        })
+    ),
     'CREATE CONSTRAINT tag_slug_unique IF NOT EXISTS FOR (t:Tag) REQUIRE (t.slug) IS UNIQUE',
     'CREATE TEXT INDEX tag_name_text_idx IF NOT EXISTS FOR (t:Tag) ON (t.name)',
     'CREATE INDEX has_role_id_idx IF NOT EXISTS FOR ()-[r:HAS_ROLE]-() ON (r.roleId)',
@@ -291,5 +317,7 @@ export * from './AppManifestVersion';
 export * from './AppStoreListing';
 export * from './CredentialActivity';
 export * from './CredentialRefresh';
+export * from './CredentialSharePreview';
 export * from './ShareLink';
 export * from './StatusList';
+export * from './Campaign';

package/src/routes/app-store.ts

@@ -1,5 +1,4 @@
 import { TRPCError } from '@trpc/server';
-import { v4 as uuid } from 'uuid';
 import { z } from 'zod';
 import {
     PendingListingUpdateValidator,
@@ -48,6 +47,7 @@ import {
     invalidateConsentContractForListingByScopeHashCache,
 } from '@cache/app-store.caches';
 import { logCredentialSent } from '@helpers/activity.helpers';
+import { sendAppCredentialWithActivity } from '@helpers/app-credential-delivery.helpers';
 import { getCredentialUri } from '@helpers/credential.helpers';
 import { constructUri, resolveUri } from '@helpers/uri.helpers';
 import { inflateObject } from '@helpers/objects.helpers';
@@ -947,15 +947,10 @@ export const handleSendCredentialEvent = async (
 
     perf.mark('saIssue');
 
-    // LC-1644 Phase 1d: run logCredentialSent + sendBoost in parallel. They previously
-    // ran serially because sendBoost needed activityId as a foreign key on the
-    // SentCredential relationship. We now pre-generate the activityId upfront (matching
-    // the uuid the activity log would have chosen itself) and pass it to both calls.
-    // Both writes produce the same Neo4j linkage as before; we just fan them out.
-    // At staging this saves ~40ms on the serial sum (logActivity 40ms + sendBoost 50ms).
-    const activityId = uuid();
-    const [, credentialUri] = await Promise.all([
-        logCredentialSent({
+    // Activity and delivery both write listing relationships; finish one before
+    // starting the other so one request cannot deadlock against its own writes.
+    const credentialUri = await sendAppCredentialWithActivity(
+        {
             actorProfileId: integrationOwner.profileId,
             recipientType: 'profile',
             recipientIdentifier: target.profileId,
@@ -965,20 +960,18 @@ export const handleSendCredentialEvent = async (
             listingId,
             source: 'appEvent',
             metadata: { listingId, templateAlias },
-            activityId,
-        }),
-        sendBoost({
+        },
+        {
             from: issuer,
             to: target,
             boost,
             credential,
             domain: ctx.domain,
             skipNotification: false,
-            activityId,
             integrationId: integration.id,
             listingId,
-        }),
-    ]);
+        }
+    );
 
     perf.mark('logActivityAndSendBoost');
 

package/src/routes/campaigns.ts

@@ -0,0 +1,179 @@
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import {
+    CampaignAudienceInputValidator,
+    CampaignEventValidator,
+    CampaignIdValidator,
+    CampaignStatsValidator,
+    CampaignStatusValidator,
+    CampaignValidator,
+    CreateCampaignInputValidator,
+    ListCampaignsInputValidator,
+    MyCampaignValidator,
+    PageCampaignAudienceInputValidator,
+    PaginatedCampaignAudienceValidator,
+    PaginatedCampaignsValidator,
+    UpdateCampaignInputValidator,
+    type Campaign,
+    type CampaignStats,
+    type MyCampaign,
+    type PaginatedCampaignAudience,
+    type PaginatedCampaigns,
+} from '@learncard/types';
+
+import { t, profileRouteWithoutInputCapture } from '@routes';
+import { isCampaignAdmin } from 'src/constants/campaigns';
+import { enforceRateLimits } from '@helpers/rateLimit.helpers';
+import { trace } from '@tracing';
+import { createCampaign } from '@accesslayer/campaign/create';
+import {
+    getCampaign,
+    listCampaigns,
+    getLiveCampaignsForProfile,
+    getCampaignStats,
+} from '@accesslayer/campaign/read';
+import { updateCampaign } from '@accesslayer/campaign/update';
+import { deleteCampaign } from '@accesslayer/campaign/delete';
+import {
+    addCampaignAudience,
+    previewCampaignAudience,
+    pageCampaignAudience,
+} from '@accesslayer/campaign/audience';
+import { enrollInCampaign, recordCampaignEvent } from '@accesslayer/campaign/state';
+
+const campaignAdminRoute = profileRouteWithoutInputCapture
+    .meta({ requiredScope: 'campaigns:admin' })
+    .use(({ ctx, next }) => {
+        if (!isCampaignAdmin(ctx.user.profile.profileId))
+            throw new TRPCError({
+                code: 'FORBIDDEN',
+                message: 'Campaign administrator access required',
+            });
+        return next({ ctx });
+    });
+
+const campaignUserRoute = profileRouteWithoutInputCapture.use(async ({ ctx, next }) => {
+    await enforceRateLimits([
+        {
+            key: `campaigns:user:${ctx.user.profile.profileId}`,
+            limit: 60,
+            windowSeconds: 60,
+            description: '60 campaign requests per profile per minute',
+        },
+    ]);
+    return next({ ctx });
+});
+
+const idInput = z.object({ campaignId: CampaignIdValidator }).strict();
+const noInput = z.object({}).strict().default({});
+
+export const campaignsRouter = t.router({
+    isAdmin: campaignUserRoute
+        .meta({ requiredScope: 'campaigns:read' })
+        .input(noInput)
+        .output(z.boolean())
+        .query(async ({ ctx }): Promise<boolean> =>
+            trace('route', 'campaigns:isAdmin', async () =>
+                isCampaignAdmin(ctx.user.profile.profileId)
+            )
+        ),
+    create: campaignAdminRoute
+        .input(CreateCampaignInputValidator)
+        .output(CampaignValidator)
+        .mutation(async ({ ctx, input }): Promise<Campaign> =>
+            trace('route', 'campaigns:create', () =>
+                createCampaign(input, ctx.user.profile.profileId)
+            )
+        ),
+    update: campaignAdminRoute
+        .input(UpdateCampaignInputValidator)
+        .output(CampaignValidator)
+        .mutation(async ({ input }): Promise<Campaign> =>
+            trace('route', 'campaigns:update', () => updateCampaign(input))
+        ),
+    get: campaignAdminRoute
+        .input(idInput)
+        .output(CampaignValidator)
+        .query(async ({ input }): Promise<Campaign> =>
+            trace('route', 'campaigns:get', () => getCampaign(input.campaignId))
+        ),
+    list: campaignAdminRoute
+        .input(ListCampaignsInputValidator.prefault({}))
+        .output(PaginatedCampaignsValidator)
+        .query(async ({ input }): Promise<PaginatedCampaigns> =>
+            trace('route', 'campaigns:list', () => listCampaigns(input))
+        ),
+    delete: campaignAdminRoute
+        .input(idInput)
+        .output(z.boolean())
+        .mutation(async ({ input }): Promise<boolean> =>
+            trace('route', 'campaigns:delete', () => deleteCampaign(input.campaignId))
+        ),
+    setStatus: campaignAdminRoute
+        .input(idInput.extend({ status: CampaignStatusValidator }))
+        .output(CampaignValidator)
+        .mutation(async ({ input }): Promise<Campaign> =>
+            trace('route', 'campaigns:setStatus', () =>
+                updateCampaign({ campaignId: input.campaignId, updates: { status: input.status } })
+            )
+        ),
+    previewAudience: campaignAdminRoute
+        .input(CampaignAudienceInputValidator)
+        .output(z.object({ count: z.number() }))
+        .query(async ({ input, ctx }): Promise<{ count: number }> =>
+            trace('route', 'campaigns:previewAudience', async () => ({
+                count: await previewCampaignAudience(input.campaignId, input.source, ctx.domain),
+            }))
+        ),
+    addAudience: campaignAdminRoute
+        .input(CampaignAudienceInputValidator)
+        .output(z.object({ count: z.number() }))
+        .mutation(async ({ input, ctx }): Promise<{ count: number }> =>
+            trace('route', 'campaigns:addAudience', async () => ({
+                count: await addCampaignAudience(input.campaignId, input.source, ctx.domain),
+            }))
+        ),
+    pageAudience: campaignAdminRoute
+        .input(PageCampaignAudienceInputValidator)
+        .output(PaginatedCampaignAudienceValidator)
+        .query(async ({ input }): Promise<PaginatedCampaignAudience> =>
+            trace('route', 'campaigns:pageAudience', () =>
+                pageCampaignAudience(input.campaignId, input.cursor, input.limit)
+            )
+        ),
+    getStats: campaignAdminRoute
+        .input(idInput)
+        .output(CampaignStatsValidator)
+        .query(async ({ input }): Promise<CampaignStats> =>
+            trace('route', 'campaigns:getStats', () => getCampaignStats(input.campaignId))
+        ),
+    getMyCampaigns: campaignUserRoute
+        .meta({ requiredScope: 'campaigns:read' })
+        .input(noInput)
+        .output(z.array(MyCampaignValidator))
+        .query(async ({ ctx }): Promise<MyCampaign[]> =>
+            trace('route', 'campaigns:getMyCampaigns', () =>
+                getLiveCampaignsForProfile(ctx.user.profile.profileId)
+            )
+        ),
+    recordEvent: campaignUserRoute
+        .meta({ requiredScope: 'campaigns:write' })
+        .input(idInput.extend({ event: CampaignEventValidator }))
+        .output(z.boolean())
+        .mutation(async ({ input, ctx }): Promise<boolean> =>
+            trace('route', 'campaigns:recordEvent', () =>
+                recordCampaignEvent(ctx.user.profile.profileId, input.campaignId, input.event)
+            )
+        ),
+    enroll: campaignUserRoute
+        .meta({ requiredScope: 'campaigns:write' })
+        .input(idInput)
+        .output(z.boolean())
+        .mutation(async ({ input, ctx }): Promise<boolean> =>
+            trace('route', 'campaigns:enroll', () =>
+                enrollInCampaign(ctx.user.profile.profileId, input.campaignId)
+            )
+        ),
+});
+
+export type CampaignsRouter = typeof campaignsRouter;

package/src/routes/credential-share-previews.ts

@@ -0,0 +1,74 @@
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import {
+    CredentialSharePreviewValidator,
+    PublishCredentialSharePreviewValidator,
+} from '@learncard/types';
+import {
+    createCredentialSharePreview,
+    deleteCredentialSharePreview,
+    getCredentialSharePreview,
+} from '@accesslayer/credential-share-previews';
+import { t, profileRoute, openRoute } from '@routes';
+
+const Id = z.string().uuid();
+const previewOutput = CredentialSharePreviewValidator;
+const openapi = (method: 'GET' | 'POST', path: `/${string}`, summary: string) => ({
+    method,
+    path,
+    summary,
+    tags: ['Credential Share Previews'],
+});
+
+export const credentialSharePreviewsRouter = t.router({
+    publish: profileRoute
+        .meta({
+            openapi: {
+                ...openapi(
+                    'POST',
+                    '/credential-share-previews',
+                    'Publish credential share preview'
+                ),
+                protect: true,
+            },
+        })
+        .input(PublishCredentialSharePreviewValidator)
+        .output(Id)
+        .mutation(async ({ ctx, input }) => {
+            const id = await createCredentialSharePreview(ctx.user.profile.profileId, input);
+            if (!id) throw new TRPCError({ code: 'NOT_FOUND' });
+            return id;
+        }),
+    delete: profileRoute
+        .meta({
+            openapi: {
+                ...openapi(
+                    'POST',
+                    '/credential-share-previews/{id}/delete',
+                    'Delete owned credential share preview'
+                ),
+                protect: true,
+            },
+        })
+        .input(z.object({ id: Id }).strict())
+        .output(z.boolean())
+        .mutation(({ ctx, input }) =>
+            deleteCredentialSharePreview(ctx.user.profile.profileId, input.id)
+        ),
+    get: openRoute
+        .meta({
+            openapi: openapi(
+                'GET',
+                '/credential-share-previews/{id}',
+                'Get public credential share preview'
+            ),
+        })
+        .input(z.object({ id: Id, shareUri: z.string().min(1).max(4096) }).strict())
+        .output(previewOutput)
+        .query(async ({ input }) => {
+            const preview = await getCredentialSharePreview(input.id, input.shareUri);
+            if (!preview) throw new TRPCError({ code: 'NOT_FOUND' });
+            return preview;
+        }),
+});
+export type CredentialSharePreviewsRouter = typeof credentialSharePreviewsRouter;

package/src/routes/profiles.ts

@@ -113,6 +113,7 @@ const UpdateProfileInputValidator = z.object({
     image: z.string().optional(),
     heroImage: z.string().optional(),
     websiteLink: z.string().optional(),
+    linkedInOrganizationId: z.string().regex(/^\d*$/).optional(),
     type: z.string().optional(),
     email: z.string().optional(),
     notificationsWebhook: z.string().optional(),
@@ -599,6 +600,7 @@ export const profilesRouter = t.router({
                 image,
                 heroImage,
                 websiteLink,
+                linkedInOrganizationId,
                 type,
                 email,
                 notificationsWebhook,
@@ -662,6 +664,11 @@ export const profilesRouter = t.router({
             if (typeof bio === 'string') actualUpdates.bio = bio;
             if (typeof heroImage === 'string') actualUpdates.heroImage = heroImage;
             if (typeof websiteLink === 'string') actualUpdates.websiteLink = websiteLink;
+            if (typeof linkedInOrganizationId === 'string') {
+                // Neo4j removes a property when SET += receives null.
+                (actualUpdates as Record<string, unknown>).linkedInOrganizationId =
+                    linkedInOrganizationId || null;
+            }
             if (typeof type === 'string') actualUpdates.type = type;
             if (typeof notificationsWebhook === 'string')
                 actualUpdates.notificationsWebhook = notificationsWebhook;

package/src/routes/skills-semantic-search.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveTenantFromRequest } from '@learncard/email-templates';
+import type { ProfileType } from 'types/profile';
+
+/**
+ * LC-2206: semantic search read routing behind SKILL_EMBEDDING_BEDROCK_READ_ENABLED, through
+ * the real router and embedding helpers. Bedrock and Google are faked; nothing leaves the box.
+ */
+
+const mocks = vi.hoisted(() => ({
+    store: new Map<string, string>(),
+    getProfileByDid: vi.fn(),
+    searchSkillsByEmbedding: vi.fn(),
+}));
+
+vi.mock('@cache', () => ({
+    default: {
+        get: vi.fn(async (key: string) => mocks.store.get(key)),
+        set: vi.fn(async (key: string, value: string) => {
+            mocks.store.set(key, value);
+            return 'OK';
+        }),
+        incr: vi.fn(async () => 1),
+        node: {},
+    },
+}));
+vi.mock('@accesslayer/profile/read', () => ({ getProfileByDid: mocks.getProfileByDid }));
+vi.mock('@accesslayer/skill/read', async importOriginal => ({
+    ...(await importOriginal<typeof import('@accesslayer/skill/read')>()),
+    searchSkillsByEmbedding: mocks.searchSkillsByEmbedding,
+}));
+
+import { environment } from '@environment';
+import {
+    setLegacySkillEmbeddingForTests,
+    setSkillEmbeddingInvokeForTests,
+} from '@helpers/skill-embedding.helpers';
+
+import { type Context } from './index';
+import { skillsRouter } from './skills';
+
+const profile: ProfileType = {
+    profileId: 'searcher',
+    did: 'did:key:searcher',
+    displayName: 'Searcher',
+    shortBio: '',
+    bio: '',
+};
+
+const context: Context = {
+    domain: 'network.example.com',
+    tenant: resolveTenantFromRequest({}),
+    user: { did: profile.did, isChallengeValid: true, scope: '*:*' },
+};
+
+const vector = (dimension: number) =>
+    Array.from({ length: dimension }, () => 1 / Math.sqrt(dimension));
+
+const novaBody = (values: number[]) =>
+    new TextEncoder().encode(
+        JSON.stringify({ embeddings: [{ embeddingType: 'TEXT', embedding: values }] })
+    );
+
+const ORIGINAL = {
+    SKILL_EMBEDDING_BEDROCK_ENABLED: environment.SKILL_EMBEDDING_BEDROCK_ENABLED,
+    SKILL_EMBEDDING_BEDROCK_READ_ENABLED: environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED,
+    SKILL_EMBEDDING_GOOGLE_API_KEY: environment.SKILL_EMBEDDING_GOOGLE_API_KEY,
+};
+
+describe('skills.semanticSearchSkills read routing (LC-2206)', () => {
+    const invoke = vi.fn();
+    const legacyEmbed = vi.fn();
+
+    const search = (text = 'help customers with complaints') =>
+        skillsRouter.createCaller(context).semanticSearchSkills({ text, limit: 5 });
+
+    beforeEach(() => {
+        mocks.store.clear();
+        mocks.getProfileByDid.mockResolvedValue(profile);
+        mocks.searchSkillsByEmbedding.mockReset().mockResolvedValue([]);
+        invoke.mockReset().mockImplementation(async () => novaBody(vector(1024)));
+        legacyEmbed
+            .mockReset()
+            .mockImplementation(async (texts: string[]) => texts.map(() => vector(768)));
+        setSkillEmbeddingInvokeForTests(invoke as never);
+        setLegacySkillEmbeddingForTests(legacyEmbed);
+
+        // Deployed shape: Nova writes on, Google key present for the legacy read path.
+        environment.SKILL_EMBEDDING_BEDROCK_ENABLED = true;
+        environment.SKILL_EMBEDDING_GOOGLE_API_KEY = 'legacy-google-key';
+    });
+
+    afterEach(() => {
+        setSkillEmbeddingInvokeForTests(undefined);
+        setLegacySkillEmbeddingForTests(undefined);
+        Object.assign(environment, ORIGINAL);
+    });
+
+    it('flag off (default): queries the legacy 768-d index with a Google query embedding', async () => {
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = false;
+
+        await search();
+
+        expect(legacyEmbed).toHaveBeenCalledWith(['help customers with complaints']);
+        expect(invoke).not.toHaveBeenCalled();
+        const [embedding, limit, frameworkId, index] = mocks.searchSkillsByEmbedding.mock.calls[0]!;
+        expect(embedding).toHaveLength(768);
+        expect(limit).toBe(5);
+        expect(frameworkId).toBeUndefined();
+        expect(index).toEqual({
+            source: 'legacy',
+            indexName: 'skill_embedding_vector_idx',
+            dimension: 768,
+        });
+    });
+
+    it('flag on: queries the Nova 1024-d index with a TEXT_RETRIEVAL query embedding', async () => {
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = true;
+
+        await search();
+
+        expect(legacyEmbed).not.toHaveBeenCalled();
+        expect(invoke).toHaveBeenCalledTimes(1);
+        const request = JSON.parse(invoke.mock.calls[0]![0].body);
+        expect(request.singleEmbeddingParams.embeddingPurpose).toBe('TEXT_RETRIEVAL');
+        const [embedding, , , index] = mocks.searchSkillsByEmbedding.mock.calls[0]!;
+        expect(embedding).toHaveLength(1024);
+        expect(index).toEqual({
+            source: 'nova',
+            indexName: 'skill_embedding_nova2_v1_0_d1024_idx',
+            dimension: 1024,
+        });
+    });
+
+    it('flipping the flag back off is the rollback: the same query goes back to legacy', async () => {
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = true;
+        await search();
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = false;
+        await search();
+
+        const indexes = mocks.searchSkillsByEmbedding.mock.calls.map(call => call[3].indexName);
+        expect(indexes).toEqual([
+            'skill_embedding_nova2_v1_0_d1024_idx',
+            'skill_embedding_vector_idx',
+        ]);
+        // The cached Nova vector was not reused for the legacy index (or vice versa).
+        expect(mocks.searchSkillsByEmbedding.mock.calls[1]![0]).toHaveLength(768);
+        expect(legacyEmbed).toHaveBeenCalledTimes(1);
+        expect(invoke).toHaveBeenCalledTimes(1);
+    });
+
+    it('flag off keeps main behaviour for long text (no Nova 8,192-character limit)', async () => {
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = false;
+        await expect(search('x'.repeat(9000))).resolves.toMatchObject({ records: [] });
+
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = true;
+        await expect(search('x'.repeat(9000))).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+
+    it('flag off without a Google key fails closed instead of querying Nova', async () => {
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED = false;
+        environment.SKILL_EMBEDDING_GOOGLE_API_KEY = undefined;
+
+        await expect(search()).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE' });
+        expect(invoke).not.toHaveBeenCalled();
+        expect(mocks.searchSkillsByEmbedding).not.toHaveBeenCalled();
+    });
+});