@learncard/network-brain-service 4.0.4 → 4.1.0

package/src/accesslayer/skill/update.ts

@@ -2,6 +2,13 @@ import { TRPCError } from '@trpc/server';
 
 import { neogma } from '@instance';
 import type { FlatSkillType } from 'types/skill';
+import {
+    LEGACY_GOOGLE_SKILL_EMBEDDING_DIMENSION,
+    buildSkillEmbeddingUpdateParams,
+    buildSkillEmbeddingUpdateQuery,
+    type SkillEmbeddingGeneration,
+    type SkillEmbeddingSource,
+} from '../../config/skillEmbedding';
 
 export type UpdateSkillInput = Partial<
     Omit<FlatSkillType, 'id' | 'frameworkId' | 'createdAt' | 'updatedAt' | 'parentId'>
@@ -154,11 +161,46 @@ export const deleteSkill = async (
     }
 };
 
-export const updateSkillEmbedding = async (
+export type SkillEmbeddingUpdate = {
+    skillId: string;
+    frameworkId?: string;
+    embedding: number[];
+    /** sha256(identity + text); lets the backfill skip skills already embedded with this generation. */
+    embeddingKey: string;
+    generation: SkillEmbeddingGeneration;
+    /** Statement/description the vector was computed from; the write is skipped if they changed. */
+    source: SkillEmbeddingSource;
+};
+
+/** Returns false when the skill is gone or its source changed since it was embedded. */
+export const updateSkillEmbedding = async (update: SkillEmbeddingUpdate): Promise<boolean> => {
+    const { frameworkId, embedding, generation } = update;
+
+    if (embedding.length !== generation.dimension) {
+        throw new Error('Skill embedding does not match the configured dimension');
+    }
+
+    const result = await neogma.queryRunner.run(
+        buildSkillEmbeddingUpdateQuery(generation, Boolean(frameworkId)),
+        buildSkillEmbeddingUpdateParams(update)
+    );
+
+    return Number(result.records[0]?.get('count') ?? 0) > 0;
+};
+
+/**
+ * LC-2206 legacy write: the pre-Nova `s.embedding` (Google gemini-embedding-001, 768-d) exactly
+ * as main writes it, so the legacy index stays current while semantic search still reads it.
+ */
+export const updateLegacySkillEmbedding = async (
     skillId: string,
     embedding: number[],
     frameworkId?: string
 ): Promise<boolean> => {
+    if (embedding.length !== LEGACY_GOOGLE_SKILL_EMBEDDING_DIMENSION) {
+        throw new Error('Legacy skill embedding does not match the legacy dimension');
+    }
+
     if (frameworkId) {
         const result = await neogma.queryRunner.run(
             `MATCH (f:SkillFramework {id: $frameworkId})-[:CONTAINS]->(s:Skill {id: $skillId})

package/src/app.ts

@@ -19,10 +19,15 @@ import { skillFrameworksRouter, SkillFrameworksRouter } from '@routes/skill-fram
 import { skillsRouter, SkillsRouter } from '@routes/skills';
 import { integrationsRouter, IntegrationsRouter } from '@routes/integrations';
 import { appStoreRouter, AppStoreRouter } from '@routes/app-store';
+import { campaignsRouter, CampaignsRouter } from '@routes/campaigns';
 import { activityRouter, ActivityRouter } from '@routes/activity';
 import { federationRouter, FederationRouter } from '@routes/federation';
 import { shareLinksRouter, ShareLinksRouter } from '@routes/share-links';
 import { publicShareLinksRouter, PublicShareLinksRouter } from '@routes/public-share-links';
+import {
+    credentialSharePreviewsRouter,
+    CredentialSharePreviewsRouter,
+} from '@routes/credential-share-previews';
 
 /** For end-to-end testing, only available in test environment */
 import { testRouter, TestRouter } from '@routes/test';
@@ -52,10 +57,12 @@ export const appRouter = t.router<{
     skills: SkillsRouter;
     integrations: IntegrationsRouter;
     appStore: AppStoreRouter;
+    campaigns: CampaignsRouter;
     activity: ActivityRouter;
     federation: FederationRouter;
     shareLinks: ShareLinksRouter;
     publicShareLinks: PublicShareLinksRouter;
+    credentialSharePreviews: CredentialSharePreviewsRouter;
     test?: TestRouter;
     bench?: BenchRouter;
 }>({
@@ -78,10 +85,12 @@ export const appRouter = t.router<{
     skills: skillsRouter,
     integrations: integrationsRouter,
     appStore: appStoreRouter,
+    campaigns: campaignsRouter,
     activity: activityRouter,
     federation: federationRouter,
     shareLinks: shareLinksRouter,
     publicShareLinks: publicShareLinksRouter,
+    credentialSharePreviews: credentialSharePreviewsRouter,
     test: environment.IS_E2E_TEST ? testRouter : undefined,
     bench: environment.ENABLE_BENCH_ROUTES ? benchRouter : undefined,
 });

package/src/config/environment.test.ts

@@ -8,6 +8,10 @@ import {
     getCredentialRefreshRuntimeEnvironment,
     parseBrainServiceEnvironment,
 } from './environment';
+import {
+    LEGACY_GOOGLE_SKILL_EMBEDDING_SEARCH_INDEX,
+    LEGACY_GOOGLE_SKILL_EMBEDDING_VECTOR_INDEX_QUERY,
+} from './skillEmbedding';
 
 const REQUIRED_ENVIRONMENT = {
     SEED: 'a'.repeat(64),
@@ -103,3 +107,207 @@ describe('credential refresh configuration', () => {
         }
     );
 });
+
+describe('LC-2206 skill embedding configuration', () => {
+    const DEPLOYED_LAMBDA = {
+        ...REQUIRED_ENVIRONMENT,
+        NODE_ENV: 'development',
+        DOMAIN_NAME: 'network.example.com',
+        AWS_LAMBDA_FUNCTION_NAME: 'lcn-brain-service-production-trpc',
+    };
+    const PRODUCTION_CONTAINER = {
+        ...REQUIRED_ENVIRONMENT,
+        NODE_ENV: 'production',
+        DOMAIN_NAME: 'network.example.com',
+    };
+
+    it('defaults to the reviewed Nova 2 model, us-east-1 and 1024 dimensions, disabled', () => {
+        expect(
+            parseBrainServiceEnvironment({ ...REQUIRED_ENVIRONMENT, NODE_ENV: 'test' })
+        ).toMatchObject({
+            SKILL_EMBEDDING_BEDROCK_ENABLED: false,
+            // Reads stay on the legacy Google index unless explicitly switched.
+            SKILL_EMBEDDING_BEDROCK_READ_ENABLED: false,
+            SKILL_EMBEDDING_BEDROCK_MODEL_ID: 'amazon.nova-2-multimodal-embeddings-v1:0',
+            SKILL_EMBEDDING_BEDROCK_REGION: 'us-east-1',
+            SKILL_EMBEDDING_DIMENSION: 1024,
+            SKILL_EMBEDDING_BEDROCK_TIMEOUT_MS: 15_000,
+            SKILL_EMBEDDING_CONCURRENCY: 1,
+        });
+    });
+
+    it.each([
+        ['deployed Lambda', DEPLOYED_LAMBDA],
+        ['production container', PRODUCTION_CONTAINER],
+    ])('accepts the allowlisted model and dimension in a %s', (_name, base) => {
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...base,
+                SKILL_EMBEDDING_BEDROCK_ENABLED: 'true',
+                SKILL_EMBEDDING_BEDROCK_MODEL_ID: 'amazon.nova-2-multimodal-embeddings-v1:0',
+                SKILL_EMBEDDING_DIMENSION: '1024',
+            })
+        ).not.toThrow();
+    });
+
+    it.each([
+        ['deployed Lambda', DEPLOYED_LAMBDA],
+        ['production container', PRODUCTION_CONTAINER],
+    ])('rejects any other model or dimension at startup in a %s', (_name, base) => {
+        // A different Nova 2 revision is valid locally but not allowlisted for deployment.
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...base,
+                SKILL_EMBEDDING_BEDROCK_MODEL_ID: 'amazon.nova-2-multimodal-embeddings-v1:1',
+            })
+        ).toThrow(/SKILL_EMBEDDING_BEDROCK_MODEL_ID/);
+
+        for (const dimension of ['256', '384', '3072']) {
+            expect(() =>
+                parseBrainServiceEnvironment({ ...base, SKILL_EMBEDDING_DIMENSION: dimension })
+            ).toThrow(/SKILL_EMBEDDING_DIMENSION/);
+        }
+
+        expect(() =>
+            parseBrainServiceEnvironment({ ...base, SKILL_EMBEDDING_BEDROCK_REGION: 'us-west-2' })
+        ).toThrow(/SKILL_EMBEDDING_BEDROCK_REGION/);
+    });
+
+    it('rejects the Google model as a Bedrock model ID and unsupported Nova dimensions everywhere', () => {
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                SKILL_EMBEDDING_BEDROCK_MODEL_ID: 'gemini-embedding-001',
+            })
+        ).toThrow(/SKILL_EMBEDDING_BEDROCK_MODEL_ID/);
+
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                SKILL_EMBEDDING_DIMENSION: '768',
+            })
+        ).toThrow(/SKILL_EMBEDDING_DIMENSION/);
+    });
+
+    it('allows other Nova 2 dimensions for local experiments', () => {
+        expect(
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'development',
+                IS_OFFLINE: 'true',
+                SKILL_EMBEDDING_DIMENSION: '384',
+            }).SKILL_EMBEDDING_DIMENSION
+        ).toBe(384);
+    });
+
+    it('refuses Bedrock API keys and endpoint overrides in deployed runtimes', () => {
+        const enabled = { ...DEPLOYED_LAMBDA, SKILL_EMBEDDING_BEDROCK_ENABLED: 'true' };
+
+        expect(() =>
+            parseBrainServiceEnvironment({ ...enabled, AWS_BEARER_TOKEN_BEDROCK: 'long-term-key' })
+        ).toThrow(/AWS_BEARER_TOKEN_BEDROCK/);
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...enabled,
+                AWS_ENDPOINT_URL_BEDROCK_RUNTIME: 'https://proxy.example.com',
+            })
+        ).toThrow(/AWS_ENDPOINT_URL_BEDROCK_RUNTIME/);
+    });
+
+    it('read flag defaults off even when Nova writes are enabled in a deployed runtime', () => {
+        const parsed = parseBrainServiceEnvironment({
+            ...DEPLOYED_LAMBDA,
+            SKILL_EMBEDDING_BEDROCK_ENABLED: 'true',
+        });
+
+        expect(parsed.SKILL_EMBEDDING_BEDROCK_ENABLED).toBe(true);
+        expect(parsed.SKILL_EMBEDDING_BEDROCK_READ_ENABLED).toBe(false);
+    });
+
+    it('accepts the read flag with Nova enabled and rejects it with Nova disabled', () => {
+        expect(
+            parseBrainServiceEnvironment({
+                ...DEPLOYED_LAMBDA,
+                SKILL_EMBEDDING_BEDROCK_ENABLED: 'true',
+                SKILL_EMBEDDING_BEDROCK_READ_ENABLED: 'true',
+            }).SKILL_EMBEDDING_BEDROCK_READ_ENABLED
+        ).toBe(true);
+
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                SKILL_EMBEDDING_BEDROCK_READ_ENABLED: 'true',
+            })
+        ).toThrow(/SKILL_EMBEDDING_BEDROCK_READ_ENABLED=true/);
+    });
+
+    it('keeps the legacy Google settings for the flag-off read path', () => {
+        expect(
+            parseBrainServiceEnvironment({
+                ...DEPLOYED_LAMBDA,
+                SKILL_EMBEDDING_BEDROCK_ENABLED: 'true',
+                SKILL_EMBEDDING_GOOGLE_API_KEY: 'legacy-google-key',
+                SKILL_EMBEDDING_GOOGLE_MODEL: 'gemini-embedding-001',
+            })
+        ).toMatchObject({
+            SKILL_EMBEDDING_GOOGLE_API_KEY: 'legacy-google-key',
+            SKILL_EMBEDDING_GOOGLE_MODEL: 'gemini-embedding-001',
+        });
+    });
+
+    it("keeps main's legacy 768-d index definition for the flag-off read path", () => {
+        expect(LEGACY_GOOGLE_SKILL_EMBEDDING_VECTOR_INDEX_QUERY).toBe(
+            "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'}}"
+        );
+        expect(LEGACY_GOOGLE_SKILL_EMBEDDING_SEARCH_INDEX).toEqual({
+            source: 'legacy',
+            indexName: 'skill_embedding_vector_idx',
+            dimension: 768,
+        });
+    });
+
+    it('requires Bedrock embeddings to be enabled for the startup backfill', () => {
+        expect(() =>
+            parseBrainServiceEnvironment({
+                ...REQUIRED_ENVIRONMENT,
+                NODE_ENV: 'test',
+                SKILL_EMBEDDING_BACKFILL_ON_STARTUP: 'true',
+            })
+        ).toThrow(/SKILL_EMBEDDING_BEDROCK_ENABLED/);
+    });
+
+    it.each([
+        'config.dev.json',
+        'config.production.json',
+        'config.scouts.dev.json',
+        'config.scouts.production.json',
+    ])(
+        'checked-in %s enables Nova writes, keeps reads on legacy, allowlisted values only',
+        stageFile => {
+            const configPath = fileURLToPath(new URL(`../../config/${stageFile}`, import.meta.url));
+            const config = JSON.parse(readFileSync(configPath, 'utf8'));
+
+            expect(config).toMatchObject({
+                SKILL_EMBEDDING_BEDROCK_ENABLED: 'true',
+                SKILL_EMBEDDING_BEDROCK_MODEL_ID: 'amazon.nova-2-multimodal-embeddings-v1:0',
+                SKILL_EMBEDDING_BEDROCK_REGION: 'us-east-1',
+                SKILL_EMBEDDING_DIMENSION: '1024',
+                SKILL_EMBEDDING_BEDROCK_READ_ENABLED: 'false',
+                SKILL_EMBEDDING_GOOGLE_MODEL: 'gemini-embedding-001',
+            });
+            // Only the non-secret model name is checked in; the key comes from the secrets bundle.
+            expect(config).not.toHaveProperty('SKILL_EMBEDDING_GOOGLE_API_KEY');
+            expect(() =>
+                parseBrainServiceEnvironment({
+                    ...DEPLOYED_LAMBDA,
+                    ...config,
+                    // Credentials come from the runtime-secrets bundle in Lambda.
+                    CREDENTIAL_REFRESH_DIGEST_SECRET: 'bundle-secret',
+                })
+            ).not.toThrow();
+        }
+    );
+});

package/src/config/environment.ts

@@ -1,6 +1,16 @@
 import 'dotenv/config';
 
 import { z } from 'zod';
+import {
+    DEFAULT_SKILL_EMBEDDING_DIMENSION,
+    DEFAULT_SKILL_EMBEDDING_REGION,
+    DEFAULT_SKILL_EMBEDDING_TIMEOUT_MS,
+    DEPLOYED_SKILL_EMBEDDING_ALLOWLIST,
+    NOVA2_EMBEDDING_MODEL_ID,
+    isDeployedRuntime,
+    isNova2EmbeddingModelId,
+    isSupportedSkillEmbeddingDimension,
+} from './skillEmbedding';
 import {
     environmentPort,
     optionalEnvironmentBoolean,
@@ -11,6 +21,11 @@ import {
     requiredEnvironmentString,
 } from '@learncard/helpers';
 
+const optionalPositiveInteger = z.preprocess(
+    value => (value === '' || value === undefined ? undefined : value),
+    z.coerce.number().int().positive().optional()
+);
+
 const credentialRefreshNotificationWindowHours = z.preprocess(
     value => (value === '' || value === undefined ? undefined : value),
     z.coerce.number().finite().positive().default(24)
@@ -29,6 +44,7 @@ export const brainServiceEnvironmentShape = {
     LOGIN_PROVIDER_DID: optionalEnvironmentString,
     SIGNING_AUTHORITY_ENDPOINT: optionalEnvironmentUrl,
     APP_STORE_ADMIN_PROFILE_IDS: optionalEnvironmentString,
+    CAMPAIGN_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_SEED_OWNER_PROFILE_ID: optionalEnvironmentString,
     TRUSTED_BRAIN_SERVICES: optionalEnvironmentString,
@@ -68,8 +84,25 @@ export const brainServiceEnvironmentShape = {
     GIT_SHA: optionalEnvironmentString,
     SENTRY_DSN: optionalEnvironmentUrl,
     SENTRY_ENV: optionalEnvironmentString,
+    // LC-2206 legacy path: Google gemini-embedding-001 (768-d). Semantic search reads the legacy
+    // index with Google query embeddings while SKILL_EMBEDDING_BEDROCK_READ_ENABLED is off, and
+    // skill writes keep the legacy vectors current. Removed by the post-rollback cleanup.
     SKILL_EMBEDDING_GOOGLE_API_KEY: optionalEnvironmentString,
     SKILL_EMBEDDING_GOOGLE_MODEL: optionalEnvironmentString,
+    // LC-2206: Amazon Nova 2 embeddings on Bedrock, SigV4 with the execution role only.
+    // ENABLED turns on Nova writes (new/updated skills, backfill); READ_ENABLED switches semantic
+    // search to the Nova index. Reads default off; flipping READ_ENABLED back off is the rollback.
+    SKILL_EMBEDDING_BEDROCK_ENABLED: optionalEnvironmentBoolean.default(false),
+    SKILL_EMBEDDING_BEDROCK_READ_ENABLED: optionalEnvironmentBoolean.default(false),
+    SKILL_EMBEDDING_BEDROCK_MODEL_ID: optionalEnvironmentString,
+    SKILL_EMBEDDING_BEDROCK_REGION: optionalEnvironmentString,
+    SKILL_EMBEDDING_DIMENSION: optionalPositiveInteger,
+    SKILL_EMBEDDING_BEDROCK_TIMEOUT_MS: optionalPositiveInteger,
+    SKILL_EMBEDDING_CONCURRENCY: optionalPositiveInteger,
+    // Read only to refuse ambient overrides in deployed runtimes; never used to authenticate.
+    AWS_ENDPOINT_URL: optionalEnvironmentString,
+    AWS_ENDPOINT_URL_BEDROCK_RUNTIME: optionalEnvironmentString,
+    AWS_BEARER_TOKEN_BEDROCK: optionalEnvironmentString,
     SKILL_EMBEDDING_CACHE_TTL_SECONDS: optionalEnvironmentPort,
     SKILL_EMBEDDING_BATCH_SIZE: optionalEnvironmentPort,
     SKILL_EMBEDDING_BACKFILL_BATCH_SIZE: optionalEnvironmentPort,
@@ -100,14 +133,147 @@ export const brainServiceEnvironmentShape = {
     BITSTRING_STATUS_LIST_ALLOW_SMALL: optionalEnvironmentBoolean.default(false),
 } satisfies z.ZodRawShape;
 
+type SkillEmbeddingEnvironment = {
+    NODE_ENV: string;
+    IS_OFFLINE: boolean;
+    AWS_LAMBDA_FUNCTION_NAME?: string;
+    SKILL_EMBEDDING_BEDROCK_ENABLED: boolean;
+    SKILL_EMBEDDING_BEDROCK_READ_ENABLED: boolean;
+    SKILL_EMBEDDING_BACKFILL_ON_STARTUP: boolean;
+    SKILL_EMBEDDING_BEDROCK_MODEL_ID: string;
+    SKILL_EMBEDDING_BEDROCK_REGION: string;
+    SKILL_EMBEDDING_DIMENSION: number;
+    AWS_ENDPOINT_URL?: string;
+    AWS_ENDPOINT_URL_BEDROCK_RUNTIME?: string;
+    AWS_BEARER_TOKEN_BEDROCK?: string;
+};
+
+/**
+ * LC-2206 startup guard. Any model or dimension that Nova 2 cannot serve is always rejected;
+ * deployed runtimes (staging and production) additionally only accept the reviewed allowlist,
+ * and refuse endpoint overrides and long-term Bedrock API keys.
+ */
+export const refineSkillEmbeddingEnvironment = (
+    environment: SkillEmbeddingEnvironment,
+    context: z.RefinementCtx
+): void => {
+    const modelId = environment.SKILL_EMBEDDING_BEDROCK_MODEL_ID;
+    const dimension = environment.SKILL_EMBEDDING_DIMENSION;
+    const region = environment.SKILL_EMBEDDING_BEDROCK_REGION;
+
+    if (!isNova2EmbeddingModelId(modelId)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_BEDROCK_MODEL_ID'],
+            message: 'Must be an Amazon Nova 2 multimodal embeddings model ID',
+        });
+    }
+
+    if (!isSupportedSkillEmbeddingDimension(dimension)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_DIMENSION'],
+            message: 'Must be one of 256, 384, 1024 or 3072',
+        });
+    }
+
+    if (
+        environment.SKILL_EMBEDDING_BACKFILL_ON_STARTUP &&
+        !environment.SKILL_EMBEDDING_BEDROCK_ENABLED
+    ) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_BEDROCK_ENABLED'],
+            message: 'Required when SKILL_EMBEDDING_BACKFILL_ON_STARTUP=true',
+        });
+    }
+
+    // Nova query embeddings need Bedrock; reading the Nova index without it would fail every search.
+    if (
+        environment.SKILL_EMBEDDING_BEDROCK_READ_ENABLED &&
+        !environment.SKILL_EMBEDDING_BEDROCK_ENABLED
+    ) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_BEDROCK_ENABLED'],
+            message: 'Required when SKILL_EMBEDDING_BEDROCK_READ_ENABLED=true',
+        });
+    }
+
+    if (!isDeployedRuntime(environment)) return;
+
+    const allowlist = DEPLOYED_SKILL_EMBEDDING_ALLOWLIST;
+
+    if (!(allowlist.modelIds as readonly string[]).includes(modelId)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_BEDROCK_MODEL_ID'],
+            message: `Deployed runtimes only allow ${allowlist.modelIds.join(', ')}`,
+        });
+    }
+
+    if (!(allowlist.dimensions as readonly number[]).includes(dimension)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_DIMENSION'],
+            message: `Deployed runtimes only allow ${allowlist.dimensions.join(', ')}`,
+        });
+    }
+
+    if (!(allowlist.regions as readonly string[]).includes(region)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['SKILL_EMBEDDING_BEDROCK_REGION'],
+            message: `Deployed runtimes only allow ${allowlist.regions.join(', ')}`,
+        });
+    }
+
+    if (!environment.SKILL_EMBEDDING_BEDROCK_ENABLED) return;
+
+    for (const key of ['AWS_ENDPOINT_URL', 'AWS_ENDPOINT_URL_BEDROCK_RUNTIME'] as const) {
+        if (environment[key]) {
+            context.addIssue({
+                code: 'custom',
+                path: [key],
+                message: 'Bedrock endpoint overrides are not allowed in deployed runtimes',
+            });
+        }
+    }
+
+    if (environment.AWS_BEARER_TOKEN_BEDROCK) {
+        context.addIssue({
+            code: 'custom',
+            path: ['AWS_BEARER_TOKEN_BEDROCK'],
+            message: 'Skill embeddings use the execution role (SigV4), not Bedrock API keys',
+        });
+    }
+};
+
 export const brainServiceEnvironmentSchema = z
     .object(brainServiceEnvironmentShape)
     .transform(environment => ({
         ...environment,
         NOTIFICATIONS_SERVICE_PORT: environment.NOTIFICATIONS_SERVICE_PORT ?? 5100,
         CLIENT_APP_PORT: environment.CLIENT_APP_PORT ?? 3000,
+        SKILL_EMBEDDING_BEDROCK_MODEL_ID:
+            environment.SKILL_EMBEDDING_BEDROCK_MODEL_ID ?? NOVA2_EMBEDDING_MODEL_ID,
+        SKILL_EMBEDDING_BEDROCK_REGION:
+            environment.SKILL_EMBEDDING_BEDROCK_REGION ?? DEFAULT_SKILL_EMBEDDING_REGION,
+        SKILL_EMBEDDING_DIMENSION:
+            environment.SKILL_EMBEDDING_DIMENSION ?? DEFAULT_SKILL_EMBEDDING_DIMENSION,
+        SKILL_EMBEDDING_BEDROCK_TIMEOUT_MS: Math.min(
+            Math.max(
+                environment.SKILL_EMBEDDING_BEDROCK_TIMEOUT_MS ??
+                    DEFAULT_SKILL_EMBEDDING_TIMEOUT_MS,
+                1_000
+            ),
+            60_000
+        ),
+        SKILL_EMBEDDING_CONCURRENCY: Math.min(environment.SKILL_EMBEDDING_CONCURRENCY ?? 1, 8),
     }))
     .superRefine((environment, context) => {
+        refineSkillEmbeddingEnvironment(environment, context);
+
         if (
             environment.NODE_ENV === 'production' &&
             !environment.IS_OFFLINE &&
@@ -128,17 +294,6 @@ export const brainServiceEnvironmentSchema = z
             });
         }
 
-        if (
-            environment.SKILL_EMBEDDING_BACKFILL_ON_STARTUP &&
-            !environment.SKILL_EMBEDDING_GOOGLE_API_KEY
-        ) {
-            context.addIssue({
-                code: 'custom',
-                path: ['SKILL_EMBEDDING_GOOGLE_API_KEY'],
-                message: 'Required when SKILL_EMBEDDING_BACKFILL_ON_STARTUP=true',
-            });
-        }
-
         if (
             environment.NODE_ENV !== 'test' &&
             environment.CREDENTIAL_REFRESH_ENABLED &&

package/src/config/skillEmbedding.neo4j.test.ts

@@ -0,0 +1,138 @@
+/**
+ * LC-2206 opt-in check of the skill-embedding compare-and-set against a REAL, LOCAL Neo4j 5.
+ * Skipped unless SKILL_EMBEDDING_TEST_NEO4J_URI points at localhost; it clears every node in
+ * that database, so it refuses any other host. Never point it at staging or production.
+ *
+ *   SKILL_EMBEDDING_TEST_NEO4J_URI=bolt://127.0.0.1:7687 \
+ *     bunx vitest run --config vitest.config.ts src/config/skillEmbedding.neo4j.test.ts
+ *
+ * Unauthenticated local instances work as-is; set SKILL_EMBEDDING_TEST_NEO4J_PASSWORD otherwise.
+ */
+import neo4j, { type Driver } from 'neo4j-driver';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+import { buildSkillEmbeddingUpdateQuery, resolveSkillEmbeddingGeneration } from './skillEmbedding';
+
+const uri = process.env.SKILL_EMBEDDING_TEST_NEO4J_URI;
+const isLocal = Boolean(uri && /^(bolt|neo4j):\/\/(127\.0\.0\.1|localhost)(:\d+)?$/.test(uri));
+
+const generation = resolveSkillEmbeddingGeneration({
+    modelId: 'amazon.nova-2-multimodal-embeddings-v1:0',
+    dimension: 1024,
+    region: 'us-east-1',
+});
+const VECTOR = generation.vectorProperty;
+const KEY = generation.keyProperty;
+
+const vectorOf = (seed: number) => Array.from({ length: 4 }, (_, i) => seed + i / 10);
+
+/** Same parameters updateSkillEmbedding sends. */
+const writeParams = (key: string, statement: string, description: string | null) => ({
+    frameworkId: 'fw',
+    skillId: 's1',
+    embedding: vectorOf(key === 'old-key' ? 1 : 2),
+    embeddingKey: key,
+    sourceStatement: statement,
+    sourceDescription: description ?? '',
+});
+
+describe.skipIf(!isLocal)('skill embedding compare-and-set (local Neo4j)', () => {
+    let driver: Driver;
+
+    const run = async (query: string, params: Record<string, unknown> = {}) => {
+        const session = driver.session();
+        try {
+            return await session.run(query, params);
+        } finally {
+            await session.close();
+        }
+    };
+
+    const readSkill = async () => {
+        const result = await run(
+            `MATCH (s:Skill {id: 's1'}) RETURN s.statement AS statement, s.${KEY} AS key, s.${VECTOR} AS vector`
+        );
+        return result.records[0]!.toObject() as {
+            statement: string;
+            key: string | null;
+            vector: number[] | null;
+        };
+    };
+
+    const countOf = (result: Awaited<ReturnType<typeof run>>) =>
+        Number(result.records[0]?.get('count') ?? 0);
+
+    beforeAll(async () => {
+        const password = process.env.SKILL_EMBEDDING_TEST_NEO4J_PASSWORD;
+        driver = password
+            ? neo4j.driver(uri!, neo4j.auth.basic('neo4j', password))
+            : neo4j.driver(uri!);
+        await driver.verifyConnectivity();
+    });
+
+    afterAll(async () => {
+        await driver?.close();
+    });
+
+    beforeEach(async () => {
+        await run('MATCH (n) DETACH DELETE n');
+        await run(
+            `CREATE (f:SkillFramework {id: 'fw'})-[:CONTAINS]->(:Skill {id: 's1', frameworkId: 'fw', statement: 'Old text'})`
+        );
+    });
+
+    it('writes when the source is unchanged (null description compares as empty)', async () => {
+        for (const scoped of [true, false]) {
+            const result = await run(
+                buildSkillEmbeddingUpdateQuery(generation, scoped),
+                writeParams('new-key', 'Old text', null)
+            );
+            expect(countOf(result)).toBe(1);
+        }
+
+        expect(await readSkill()).toMatchObject({ key: 'new-key', vector: vectorOf(2) });
+    });
+
+    it('a delayed backfill write for old text cannot replace the newer live write', async () => {
+        // Live path: the edit commits, then its own vector is stored.
+        await run(`MATCH (s:Skill {id: 's1'}) SET s.statement = 'New text'`);
+        await run(
+            buildSkillEmbeddingUpdateQuery(generation, true),
+            writeParams('new-key', 'New text', null)
+        );
+
+        // Backfill read "Old text" before the edit and finishes afterwards.
+        const stale = await run(
+            buildSkillEmbeddingUpdateQuery(generation, true),
+            writeParams('old-key', 'Old text', null)
+        );
+
+        expect(countOf(stale)).toBe(0);
+        expect(await readSkill()).toMatchObject({
+            statement: 'New text',
+            key: 'new-key',
+            vector: vectorOf(2),
+        });
+    });
+
+    it('waits for an in-flight skill update and then re-checks the source', async () => {
+        // A skill update holds the node's write lock with new text, not yet committed.
+        const editSession = driver.session();
+        const edit = editSession.beginTransaction();
+        await edit.run(`MATCH (s:Skill {id: 's1'}) SET s.statement = 'New text'`);
+
+        // The backfill write for the old text starts while that update is open...
+        const stale = run(
+            buildSkillEmbeddingUpdateQuery(generation, true),
+            writeParams('old-key', 'Old text', null)
+        );
+        await new Promise(resolve => setTimeout(resolve, 300));
+
+        // ...and the update commits.
+        await edit.commit();
+        await editSession.close();
+
+        expect(countOf(await stale)).toBe(0);
+        expect(await readSkill()).toMatchObject({ statement: 'New text', key: null, vector: null });
+    });
+});