@learncard/network-brain-service 4.0.3 → 4.1.0

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

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { BindParam, QueryBuilder } from 'neogma';
+import { neogma } from '@instance';
+import { CredentialSharePreview } from '@models';
+import type {
+    CredentialSharePreview as Preview,
+    PublishCredentialSharePreview,
+} from '@learncard/types';
+
+// shareUri is a client-supplied match key, not proof of presentation ownership or issuer claims.
+export const createCredentialSharePreview = async (
+    ownerProfileId: string,
+    input: PublishCredentialSharePreview
+): Promise<string | null> => {
+    const id = input.id ?? randomUUID();
+    const now = new Date().toISOString();
+    const params = {
+        id,
+        ownerProfileId,
+        name: input.name,
+        issuer: input.issuer,
+        shareUri: input.shareUri,
+        image: input.image ?? null,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const result = input.id
+        ? await neogma.queryRunner.run(
+              `MATCH (owner:Profile {profileId: $ownerProfileId})-[:PUBLISHED_CREDENTIAL_SHARE_PREVIEW]->(preview:CredentialSharePreview {id: $id, shareUri: $shareUri})
+               SET preview.name = $name, preview.issuer = $issuer, preview.image = $image, preview.updatedAt = $updatedAt
+               RETURN preview.id AS id`,
+              params
+          )
+        : await neogma.queryRunner.run(
+              `MATCH (owner:Profile {profileId: $ownerProfileId})
+               CREATE (preview:CredentialSharePreview {
+                   id: $id, name: $name, issuer: $issuer, shareUri: $shareUri,
+                   image: $image, createdAt: $createdAt, updatedAt: $updatedAt
+               })
+               CREATE (owner)-[:PUBLISHED_CREDENTIAL_SHARE_PREVIEW]->(preview)
+               RETURN preview.id AS id`,
+              params
+          );
+    return result.records[0]?.get('id') ?? null;
+};
+
+export const getCredentialSharePreview = async (
+    id: string,
+    shareUri: string
+): Promise<Preview | null> => {
+    const result = await new QueryBuilder(new BindParam({ id, shareUri }))
+        .match({ model: CredentialSharePreview, identifier: 'preview' })
+        .where('preview.id = $id AND preview.shareUri = $shareUri')
+        .return('preview')
+        .limit(1)
+        .run();
+    const properties = result.records[0]?.get('preview').properties;
+    if (!properties) return null;
+    return {
+        name: String(properties.name),
+        issuer: String(properties.issuer),
+        ...(typeof properties.image === 'string' ? { image: properties.image } : {}),
+    };
+};
+
+export const deleteCredentialSharePreview = async (
+    ownerProfileId: string,
+    id: string
+): Promise<boolean> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (owner:Profile {profileId: $ownerProfileId})-[:PUBLISHED_CREDENTIAL_SHARE_PREVIEW]->(preview:CredentialSharePreview {id: $id})
+         DETACH DELETE preview RETURN count(*) AS deleted`,
+        { ownerProfileId, id }
+    );
+    return Number(result.records[0]?.get('deleted') ?? 0) > 0;
+};

package/src/accesslayer/inbox-batch/schema.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Driver, ManagedTransaction } from 'neo4j-driver';
+
+vi.mock('@instance', () => ({ neogma: { driver: { session: vi.fn() } } }));
+import { createInboxBatchSchemaInitializer } from './schema';
+
+const harness = () => {
+    const run = vi.fn().mockResolvedValue({});
+    const close = vi.fn().mockResolvedValue(undefined);
+    const executeWrite = vi.fn(async (callback: (tx: ManagedTransaction) => unknown) =>
+        callback({ run } as unknown as ManagedTransaction)
+    );
+    const driver = { session: vi.fn(() => ({ run: vi.fn(), executeWrite, close })) };
+    const ensure = createInboxBatchSchemaInitializer(driver as unknown as Driver);
+    return { run, close, executeWrite, driver, ensure };
+};
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('inbox batch schema readiness', () => {
+    it('shares in-flight readiness and runs every constraint AND index in its own managed write', async () => {
+        const { ensure, driver, executeWrite, run, close } = harness();
+        const first = ensure();
+        expect(ensure()).toBe(first);
+        await first;
+        await ensure();
+        expect(driver.session).toHaveBeenCalledTimes(1);
+        expect(executeWrite).toHaveBeenCalledTimes(10);
+        expect(run).toHaveBeenCalledTimes(10);
+        expect(
+            run.mock.calls.filter(([query]) => query.startsWith('CREATE CONSTRAINT'))
+        ).toHaveLength(4);
+        expect(run.mock.calls.filter(([query]) => query.startsWith('CREATE INDEX'))).toHaveLength(
+            6
+        );
+        expect(close).toHaveBeenCalledTimes(1);
+    });
+
+    it('lets independent API/worker initializers complete through a transient managed-transaction retry', async () => {
+        const api = harness();
+        const worker = harness();
+        // Model the driver re-entering the transaction callback after a DDL deadlock.
+        // The real-driver concurrent cold-start regression lives in inbox-batch.spec.ts.
+        const deadlock = { code: 'Neo.TransientError.Transaction.DeadlockDetected' };
+        api.run.mockRejectedValueOnce(deadlock);
+        api.executeWrite.mockImplementationOnce(async callback => {
+            await expect(callback({ run: api.run } as unknown as ManagedTransaction)).rejects.toBe(
+                deadlock
+            );
+            return callback({ run: api.run } as unknown as ManagedTransaction);
+        });
+        await expect(Promise.all([api.ensure(), worker.ensure()])).resolves.toEqual([
+            undefined,
+            undefined,
+        ]);
+        const firstQuery =
+            'CREATE CONSTRAINT inboxbatch_id IF NOT EXISTS FOR (n:InboxBatch) REQUIRE n.id IS UNIQUE';
+        expect(api.run.mock.calls.slice(0, 2)).toEqual([[firstQuery], [firstQuery]]);
+        expect(api.run).toHaveBeenCalledTimes(11);
+        expect(worker.run).toHaveBeenCalledTimes(10);
+    });
+
+    it.each([0, 4])('accepts equivalent-schema races for statement %i', async position => {
+        const { ensure, run } = harness();
+        for (let index = 0; index < position; index++) run.mockResolvedValueOnce({});
+        run.mockRejectedValueOnce({
+            code: 'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists',
+        });
+        await expect(ensure()).resolves.toBeUndefined();
+        expect(run).toHaveBeenCalledTimes(10);
+    });
+
+    it.each([
+        'Neo.ClientError.Security.Forbidden',
+        'Neo.TransientError.Transaction.DeadlockDetected',
+    ])(
+        'propagates %s after the managed write fails and allows a later readiness attempt',
+        async code => {
+            const { ensure, executeWrite, run, close, driver } = harness();
+            const failure = { code };
+            executeWrite.mockRejectedValueOnce(failure);
+            await expect(ensure()).rejects.toBe(failure);
+            expect(run).not.toHaveBeenCalled();
+            expect(close).toHaveBeenCalledTimes(1);
+            await expect(ensure()).resolves.toBeUndefined();
+            expect(driver.session).toHaveBeenCalledTimes(2);
+            expect(run).toHaveBeenCalledTimes(10);
+            expect(close).toHaveBeenCalledTimes(2);
+        }
+    );
+});

package/src/accesslayer/inbox-batch/schema.ts

@@ -0,0 +1,54 @@
+import type { Driver } from 'neo4j-driver';
+import { neogma } from '@instance';
+
+const SCHEMA_QUERIES = [
+    ...['InboxBatch', 'InboxBatchItem', 'InboxBatchIssuer', 'InboxBatchReplay'].map(
+        label =>
+            `CREATE CONSTRAINT ${label.toLowerCase()}_id IF NOT EXISTS FOR (n:${label}) REQUIRE n.id IS UNIQUE`
+    ),
+    'CREATE INDEX inbox_batch_request IF NOT EXISTS FOR (b:InboxBatch) ON (b.issuer, b.requestId)',
+    'CREATE INDEX inbox_batch_dispatch IF NOT EXISTS FOR (i:InboxBatchItem) ON (i.state, i.dispatchAt)',
+    'CREATE INDEX inbox_batch_recovery IF NOT EXISTS FOR (i:InboxBatchItem) ON (i.state, i.leaseUntil)',
+    'CREATE INDEX inbox_batch_replay_owner IF NOT EXISTS FOR (r:InboxBatchReplay) ON (r.itemId)',
+    'CREATE INDEX inbox_batch_completed IF NOT EXISTS FOR (b:InboxBatch) ON (b.completedAt)',
+    'CREATE INDEX inbox_batch_replay_expiry IF NOT EXISTS FOR (r:InboxBatchReplay) ON (r.expiresAt)',
+];
+
+/** Each API/worker process shares readiness locally; the driver retries cross-process DDL deadlocks. */
+export const createInboxBatchSchemaInitializer = (
+    driver: Pick<Driver, 'session'>
+): (() => Promise<void>) => {
+    let readiness: Promise<void> | undefined;
+    return (): Promise<void> => {
+        if (!readiness) {
+            const pending = (async (): Promise<void> => {
+                const session = driver.session();
+                try {
+                    for (const query of SCHEMA_QUERIES) {
+                        try {
+                            // One schema statement per managed transaction. IF NOT EXISTS is
+                            // idempotent, but competing cold processes can still deadlock while
+                            // acquiring label locks. Auto-commit queryRunner.run does not retry.
+                            await session.executeWrite(tx => tx.run(query));
+                        } catch (error) {
+                            if (
+                                (error as { code?: string } | null)?.code !==
+                                'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists'
+                            )
+                                throw error;
+                        }
+                    }
+                } finally {
+                    await session.close();
+                }
+            })();
+            readiness = pending;
+            void pending.catch(() => {
+                if (readiness === pending) readiness = undefined;
+            });
+        }
+        return readiness;
+    };
+};
+
+export const ensureInboxBatchConstraints = createInboxBatchSchemaInitializer(neogma.driver);

package/src/accesslayer/inbox-batch/store.ts

@@ -6,49 +6,13 @@ import { neogma } from '@instance';
 import { encryptInboxCredential, decryptInboxCredential } from '@helpers/inbox-encryption.helpers';
 import type { BatchItem, BatchJob, BatchReplayStore, InboxDispatchLease } from 'types/inbox-batch';
 import { getInboxBatchState } from '@helpers/inbox-batch-status.helpers';
+import { ensureInboxBatchConstraints } from './schema';
 
 export const DAY = 86_400_000;
 export const LEASE_MS = 360_000;
 const CLEANUP_MARGIN_MS = 5_000;
 
-let readiness: Promise<void> | undefined;
-export const ensureInboxBatchConstraints = (): Promise<void> => {
-    if (!readiness) {
-        readiness = (async () => {
-            for (const label of [
-                'InboxBatch',
-                'InboxBatchItem',
-                'InboxBatchIssuer',
-                'InboxBatchReplay',
-            ]) {
-                try {
-                    await neogma.queryRunner.run(
-                        `CREATE CONSTRAINT ${label.toLowerCase()}_id IF NOT EXISTS FOR (n:${label}) REQUIRE n.id IS UNIQUE`
-                    );
-                } catch (error) {
-                    if (
-                        (error as { code?: string }).code !==
-                        'Neo.ClientError.Schema.EquivalentSchemaRuleAlreadyExists'
-                    )
-                        throw error;
-                }
-            }
-            for (const query of [
-                'CREATE INDEX inbox_batch_request IF NOT EXISTS FOR (b:InboxBatch) ON (b.issuer, b.requestId)',
-                'CREATE INDEX inbox_batch_dispatch IF NOT EXISTS FOR (i:InboxBatchItem) ON (i.state, i.dispatchAt)',
-                'CREATE INDEX inbox_batch_recovery IF NOT EXISTS FOR (i:InboxBatchItem) ON (i.state, i.leaseUntil)',
-                'CREATE INDEX inbox_batch_replay_owner IF NOT EXISTS FOR (r:InboxBatchReplay) ON (r.itemId)',
-                'CREATE INDEX inbox_batch_completed IF NOT EXISTS FOR (b:InboxBatch) ON (b.completedAt)',
-                'CREATE INDEX inbox_batch_replay_expiry IF NOT EXISTS FOR (r:InboxBatchReplay) ON (r.expiresAt)',
-            ])
-                await neogma.queryRunner.run(query);
-        })();
-        void readiness.catch(() => {
-            readiness = undefined;
-        });
-    }
-    return readiness;
-};
+export { ensureInboxBatchConstraints } from './schema';
 
 const transaction = async <T>(fn: (tx: ManagedTransaction) => Promise<T>): Promise<T> => {
     await ensureInboxBatchConstraints();

package/src/accesslayer/profile/delete.ts

@@ -27,5 +27,11 @@ export const deleteProfile = async (profile: ProfileType): Promise<void> => {
         { profileId: profile.profileId }
     );
 
+    // Delete share previews owned by this profile to prevent orphaned nodes.
+    await neogma.queryRunner.run(
+        `MATCH (p:Profile {profileId: $profileId})-[:PUBLISHED_CREDENTIAL_SHARE_PREVIEW]->(preview:CredentialSharePreview)
+         DETACH DELETE preview`,
+        { profileId: profile.profileId }
+    );
     await Profile.delete({ detach: true, where: { profileId: profile.profileId } });
 };

package/src/accesslayer/skill/read.ts

@@ -3,6 +3,10 @@ import { int } from 'neo4j-driver';
 import { convertObjectRegExpToNeo4j, buildWhereClause } from '@helpers/neo4j.helpers';
 import type { FlatSkillType, SkillType } from 'types/skill';
 import type { SkillQuery } from '@learncard/types';
+import type {
+    SkillEmbeddingGeneration,
+    SkillEmbeddingSearchIndex,
+} from '../../config/skillEmbedding';
 
 export const doesProfileManageSkill = async (
     profileId: string,
@@ -448,21 +452,36 @@ export type SkillEmbeddingSearchResult = {
     score: number;
 };
 
+/** Drop stored vectors (current and legacy generations) from node properties returned to callers. */
+const withoutEmbeddingProperties = (props: Record<string, unknown>): Record<string, unknown> =>
+    Object.fromEntries(Object.entries(props).filter(([key]) => !key.startsWith('embedding')));
+
+/**
+ * LC-2206: query one vector index (the Nova generation's, or the legacy Google one while
+ * SKILL_EMBEDDING_BEDROCK_READ_ENABLED is off). Vectors from other models or dimensions live
+ * in other properties and indexes, so one query never mixes embedding spaces.
+ */
 export const searchSkillsByEmbedding = async (
     embedding: number[],
     limit: number,
-    frameworkId?: string
+    frameworkId: string | undefined,
+    index: Pick<SkillEmbeddingSearchIndex, 'indexName' | 'dimension'>
 ): Promise<SkillEmbeddingSearchResult[]> => {
+    if (embedding.length !== index.dimension) {
+        throw new Error('Skill search embedding does not match the index dimension');
+    }
+
     const normalizedLimit = Math.min(Math.max(limit, 1), 200);
     const queryLimit = frameworkId ? Math.min(normalizedLimit * 3, 200) : normalizedLimit;
 
     const result = await neogma.queryRunner.run(
-        `CALL db.index.vector.queryNodes('skill_embedding_vector_idx', $limit, $embedding)
+        `CALL db.index.vector.queryNodes($indexName, $limit, $embedding)
          YIELD node, score
          WHERE $frameworkId IS NULL OR node.frameworkId = $frameworkId
          RETURN node AS s, score AS score
          ORDER BY score DESC`,
         {
+            indexName: index.indexName,
             limit: int(queryLimit),
             embedding,
             frameworkId: frameworkId ?? null,
@@ -471,7 +490,7 @@ export const searchSkillsByEmbedding = async (
 
     const rows = result.records.map(record => {
         const node = record.get('s') as { properties?: Record<string, unknown> } | undefined;
-        const props = (node?.properties ?? {}) as Record<string, unknown>;
+        const props = withoutEmbeddingProperties(node?.properties ?? {});
         const skill = {
             ...props,
             type: (props.type as string | undefined) ?? 'skill',
@@ -486,30 +505,51 @@ export const searchSkillsByEmbedding = async (
     return rows.filter(row => row.skill.frameworkId === frameworkId).slice(0, normalizedLimit);
 };
 
-export const getSkillsMissingEmbedding = async (
+export type SkillEmbeddingCandidate = {
+    id: string;
+    frameworkId?: string;
+    statement: string;
+    description?: string | null;
+    code?: string | null;
+    /** sha256(identity + text) stored with the current generation's vector, if any. */
+    embeddingKey: string | null;
+    hasEmbedding: boolean;
+};
+
+/**
+ * Page through every skill (ordered by id) with its current-generation embedding key, without
+ * loading any vectors. The caller compares keys to decide which skills need (re-)embedding,
+ * which makes the backfill idempotent and resumable from any cursor.
+ */
+export const getSkillEmbeddingCandidates = async (
+    generation: SkillEmbeddingGeneration,
     limit: number,
     cursorId?: string | null
-): Promise<Paginated<FlatSkillType>> => {
+): Promise<Paginated<SkillEmbeddingCandidate>> => {
     const normalizedLimit = Math.min(Math.max(limit, 1), 500);
 
+    // Property names come from resolveSkillEmbeddingGeneration ([a-z0-9_] only).
     const result = await neogma.queryRunner.run(
         `MATCH (s:Skill)
-         WHERE s.embedding IS NULL
-         AND ($cursorId IS NULL OR s.id > $cursorId)
-         RETURN s AS s
+         WHERE $cursorId IS NULL OR s.id > $cursorId
+         RETURN s.id AS id, s.frameworkId AS frameworkId, s.statement AS statement,
+                s.description AS description, s.code AS code,
+                s.${generation.keyProperty} AS embeddingKey,
+                s.${generation.vectorProperty} IS NOT NULL AS hasEmbedding
          ORDER BY s.id
          LIMIT $limitPlusOne`,
         { cursorId: cursorId ?? null, limitPlusOne: int(normalizedLimit + 1) }
     );
 
-    const all = result.records.map(record => {
-        const node = record.get('s') as { properties?: Record<string, unknown> } | undefined;
-        const props = (node?.properties ?? {}) as Record<string, unknown>;
-        return {
-            ...props,
-            type: (props.type as string | undefined) ?? 'skill',
-        } as FlatSkillType;
-    });
+    const all = result.records.map(record => ({
+        id: String(record.get('id')),
+        frameworkId: (record.get('frameworkId') as string | null) ?? undefined,
+        statement: String(record.get('statement') ?? ''),
+        description: record.get('description') as string | null,
+        code: record.get('code') as string | null,
+        embeddingKey: (record.get('embeddingKey') as string | null) ?? null,
+        hasEmbedding: Boolean(record.get('hasEmbedding')),
+    }));
 
     const hasMore = all.length > normalizedLimit;
     const page = all.slice(0, normalizedLimit);

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,
 });