@learncard/network-brain-service 4.0.4 → 4.1.0

package/src/accesslayer/campaign/create.ts

@@ -0,0 +1,47 @@
+import { TRPCError } from '@trpc/server';
+import {
+    CampaignValidator,
+    CreateCampaignInputValidator,
+    type Campaign,
+    type CreateCampaignInput,
+} from '@learncard/types';
+
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+import { ensureCampaignConstraints } from '../../models/campaign-constraints';
+import { campaignProperties } from './shared';
+
+export const createCampaign = async (
+    input: CreateCampaignInput,
+    createdByProfileId: string
+): Promise<Campaign> => {
+    const parsed = CreateCampaignInputValidator.parse(input);
+    const now = new Date().toISOString();
+    const campaign = CampaignValidator.parse({
+        ...parsed,
+        message: { ...parsed.message, id: parsed.id },
+        createdAt: now,
+        updatedAt: now,
+    });
+    await ensureCampaignConstraints();
+    try {
+        await traceDb('campaign:create', () =>
+            neogma.queryRunner.run('CREATE (c:Campaign) SET c = $properties', {
+                properties: { ...campaignProperties(campaign), createdByProfileId },
+            })
+        );
+    } catch (error) {
+        if (
+            (error as { code?: string })?.code ===
+            'Neo.ClientError.Schema.ConstraintValidationFailed'
+        ) {
+            throw new TRPCError({
+                code: 'CONFLICT',
+                message: 'Campaign ID already exists',
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    return campaign;
+};

package/src/accesslayer/campaign/delete.ts

@@ -0,0 +1,18 @@
+import { TRPCError } from '@trpc/server';
+
+import { lockCampaign, withCampaignTransaction } from './shared';
+
+export const deleteCampaign = async (campaignId: string): Promise<boolean> =>
+    withCampaignTransaction('campaign:delete', async transaction => {
+        const campaign = await lockCampaign(transaction, campaignId);
+        if (campaign.status === 'live' || campaign.status === 'paused') {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: 'Archive live or paused campaigns before deleting them',
+            });
+        }
+        await transaction.run('MATCH (c:Campaign {id: $campaignId}) DETACH DELETE c', {
+            campaignId,
+        });
+        return true;
+    });

package/src/accesslayer/campaign/read.ts

@@ -0,0 +1,125 @@
+import { TRPCError } from '@trpc/server';
+import { int, isInt } from 'neo4j-driver';
+import {
+    CampaignUserStateValidator,
+    type Campaign,
+    type CampaignStats,
+    type ListCampaignsInput,
+    type MyCampaign,
+    type PaginatedCampaigns,
+} from '@learncard/types';
+
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+import {
+    campaignAgePredicate,
+    campaignTimeParams,
+    liveCampaignPredicate,
+    parseCampaign,
+    safeParseCampaign,
+} from './shared';
+
+export const getCampaign = async (campaignId: string): Promise<Campaign> => {
+    const result = await traceDb('campaign:get', () =>
+        neogma.queryRunner.run(
+            'MATCH (c:Campaign {id: $campaignId}) RETURN c.definition AS definition',
+            { campaignId }
+        )
+    );
+    if (!result.records.length)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Campaign not found' });
+    return parseCampaign(result.records[0]!.get('definition'));
+};
+
+export const listCampaigns = async ({
+    cursor,
+    limit = 100,
+    status,
+}: ListCampaignsInput): Promise<PaginatedCampaigns> => {
+    const result = await traceDb('campaign:list', () =>
+        neogma.queryRunner.run(
+            `MATCH (c:Campaign) WHERE ($cursor IS NULL OR c.id > $cursor)
+         AND ($status IS NULL OR c.status = $status)
+         RETURN c.definition AS definition ORDER BY c.id LIMIT $limit`,
+            { cursor: cursor ?? null, status: status ?? null, limit: int(limit + 1) }
+        )
+    );
+    const rows = result.records.map(record => parseCampaign(record.get('definition')));
+    const hasMore = rows.length > limit;
+    const records = rows.slice(0, limit);
+    return { records, hasMore, cursor: hasMore ? records.at(-1)?.id : undefined };
+};
+
+export const getLiveCampaignsForProfile = async (
+    profileId: string,
+    now = new Date()
+): Promise<MyCampaign[]> => {
+    const result = await traceDb('campaign:getMyCampaigns', () =>
+        neogma.queryRunner.run(
+            `MATCH (p:Profile {profileId: $profileId}), (c:Campaign)
+         WHERE ${liveCampaignPredicate} AND ${campaignAgePredicate}
+           AND (c.selfEnroll = true OR EXISTS { MATCH (p)-[:IN_CAMPAIGN_AUDIENCE]->(c) })
+         OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+         RETURN c.id AS campaignId, c.definition AS definition, properties(state) AS state
+         ORDER BY c.id`,
+            { profileId, ...campaignTimeParams(now) }
+        )
+    );
+    return result.records.flatMap(record => {
+        const campaign = safeParseCampaign(record.get('definition'));
+        if (!campaign) {
+            console.warn('campaign:getMyCampaigns skipped invalid stored definition', {
+                campaignId: record.get('campaignId'),
+            });
+            return [];
+        }
+        if (!campaign.channels.includes('inApp') || !campaign.message.enabled) return [];
+        const state = Object.fromEntries(
+            Object.entries(record.get('state') ?? {}).map(([key, value]) => [
+                key,
+                isInt(value) ? value.toNumber() : value,
+            ])
+        );
+        return [
+            {
+                campaign: {
+                    id: campaign.id,
+                    message: campaign.message,
+                    startsAt: campaign.startsAt,
+                    endsAt: campaign.endsAt,
+                    selfEnroll: campaign.selfEnroll,
+                },
+                state: CampaignUserStateValidator.parse(state),
+            },
+        ];
+    });
+};
+
+export const getCampaignStats = async (campaignId: string): Promise<CampaignStats> => {
+    await getCampaign(campaignId);
+    const result = await traceDb('campaign:stats', () =>
+        neogma.queryRunner.run(
+            `MATCH (c:Campaign {id: $campaignId})
+         OPTIONAL MATCH (p:Profile)-[audience:IN_CAMPAIGN_AUDIENCE]->(c)
+         OPTIONAL MATCH (p)-[state:CAMPAIGN_STATE]->(c)
+         RETURN count(DISTINCT p) AS audience,
+           count(DISTINCT CASE WHEN audience.source = 'selfEnrolled' THEN p END) AS enrolled,
+           count(DISTINCT CASE WHEN state.notifiedAt IS NOT NULL THEN p END) AS notified,
+           count(DISTINCT CASE WHEN state.firstShownAt IS NOT NULL THEN p END) AS shown,
+           count(DISTINCT CASE WHEN state.clickedAt IS NOT NULL THEN p END) AS clicked,
+           count(DISTINCT CASE WHEN state.dismissedAt IS NOT NULL THEN p END) AS dismissed,
+           count(DISTINCT CASE WHEN state.convertedAt IS NOT NULL THEN p END) AS converted`,
+            { campaignId }
+        )
+    );
+    const record = result.records[0]!;
+    return {
+        audience: record.get('audience').toNumber(),
+        enrolled: record.get('enrolled').toNumber(),
+        notified: record.get('notified').toNumber(),
+        shown: record.get('shown').toNumber(),
+        clicked: record.get('clicked').toNumber(),
+        dismissed: record.get('dismissed').toNumber(),
+        converted: record.get('converted').toNumber(),
+    };
+};

package/src/accesslayer/campaign/shared.ts

@@ -0,0 +1,92 @@
+import { TRPCError } from '@trpc/server';
+import { CampaignValidator, type Campaign } from '@learncard/types';
+import type { ManagedTransaction } from 'neo4j-driver';
+
+import { neogma } from '@instance';
+import { traceDb } from '@tracing';
+
+const knownBirthdayPredicate = `p.dob IS NOT NULL
+    AND p.dob =~ '[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])'`;
+const managedProfilePredicate = `(EXISTS { MATCH (p)-[:MANAGED_BY]->(:Profile) }
+    OR EXISTS { MATCH (:ProfileManager)-[:MANAGES]->(p) })`;
+const serviceProfilePredicate = `(p.isServiceProfile = true AND coalesce(p.type, '') <> 'child')`;
+export const adultProfilePredicate = `${knownBirthdayPredicate}
+    AND coalesce(p.type, '') <> 'child' AND p.dob <= $adultCutoff
+    AND (${serviceProfilePredicate} OR NOT ${managedProfilePredicate})`;
+export const campaignAgePredicate = `(${knownBirthdayPredicate}
+    AND (c.excludeMinors = false OR (${adultProfilePredicate})))`;
+export const liveCampaignPredicate = `c.status = 'live'
+    AND (c.startsAt IS NULL OR c.startsAt <= $now)
+    AND (c.endsAt IS NULL OR c.endsAt > $now)`;
+
+export const campaignTimeParams = (now = new Date()): { now: string; adultCutoff: string } => {
+    const timestamp = now.toISOString();
+    // Compare calendar dates, not elapsed milliseconds. Keeping the month/day avoids
+    // JS rolling Feb 29 into March 1 and admitting March 1 birthdays a day early.
+    const adultCutoff = `${now.getUTCFullYear() - 18}${timestamp.slice(4, 10)}`;
+    return { now: timestamp, adultCutoff };
+};
+
+export const parseCampaign = (definition: string): Campaign =>
+    CampaignValidator.parse(JSON.parse(definition));
+
+export const safeParseCampaign = (definition: unknown): Campaign | undefined => {
+    if (typeof definition !== 'string') return undefined;
+    try {
+        const result = CampaignValidator.safeParse(JSON.parse(definition));
+        return result.success ? result.data : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+export const campaignProperties = (campaign: Campaign): Record<string, unknown> => ({
+    id: campaign.id,
+    name: campaign.name,
+    status: campaign.status,
+    excludeMinors: campaign.excludeMinors,
+    selfEnroll: campaign.selfEnroll,
+    createdAt: campaign.createdAt,
+    updatedAt: campaign.updatedAt,
+    definition: JSON.stringify(campaign),
+    startsAt: campaign.startsAt ?? null,
+    endsAt: campaign.endsAt ?? null,
+});
+
+export const withCampaignTransaction = async <Result>(
+    name: string,
+    work: (transaction: ManagedTransaction) => Promise<Result>
+): Promise<Result> =>
+    traceDb(name, async () => {
+        const session = neogma.queryRunner.getDriver().session();
+        try {
+            return await session.executeWrite(work);
+        } finally {
+            await session.close();
+        }
+    });
+
+/** Serialize campaign edits/audience enrollment before reading their current definition. */
+export const lockCampaign = async (
+    transaction: ManagedTransaction,
+    campaignId: string
+): Promise<Campaign> => {
+    const result = await transaction.run(
+        `MATCH (c:Campaign {id: $campaignId})
+         SET c.lockVersion = coalesce(c.lockVersion, 0) + 1
+         RETURN c.definition AS definition`,
+        { campaignId }
+    );
+    if (!result.records.length)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Campaign not found' });
+    return parseCampaign(result.records[0]!.get('definition'));
+};
+
+export const assertCampaignEditable = (campaign: Campaign): void => {
+    if (campaign.status === 'archived') {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Archived campaigns cannot be changed',
+        });
+    }
+};

package/src/accesslayer/campaign/state.ts

@@ -0,0 +1,80 @@
+import { TRPCError } from '@trpc/server';
+import { CampaignEventValidator, type CampaignEvent } from '@learncard/types';
+
+import {
+    adultProfilePredicate,
+    campaignAgePredicate,
+    campaignTimeParams,
+    liveCampaignPredicate,
+    lockCampaign,
+    withCampaignTransaction,
+} from './shared';
+
+export const enrollInCampaign = async (profileId: string, campaignId: string): Promise<boolean> =>
+    withCampaignTransaction('campaign:enroll', async transaction => {
+        const campaign = await lockCampaign(transaction, campaignId);
+        const params = campaignTimeParams();
+        if (
+            !campaign.selfEnroll ||
+            campaign.status !== 'live' ||
+            !campaign.message.enabled ||
+            !campaign.channels.includes('inApp') ||
+            (campaign.startsAt && campaign.startsAt > params.now) ||
+            (campaign.endsAt && campaign.endsAt <= params.now)
+        ) {
+            throw new TRPCError({
+                code: 'FORBIDDEN',
+                message: 'Campaign is not accepting enrollment',
+            });
+        }
+        const result = await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId}), (c:Campaign {id: $campaignId})
+             WHERE ${adultProfilePredicate}
+             MERGE (p)-[audience:IN_CAMPAIGN_AUDIENCE]->(c)
+             ON CREATE SET audience.addedAt = $now, audience.source = 'selfEnrolled'
+             RETURN p.profileId AS profileId`,
+            { profileId, campaignId, ...params }
+        );
+        if (!result.records.length)
+            throw new TRPCError({
+                code: 'FORBIDDEN',
+                message: 'Profile is not eligible for enrollment',
+            });
+        return true;
+    });
+
+export const recordCampaignEvent = async (
+    profileId: string,
+    campaignId: string,
+    rawEvent: CampaignEvent
+): Promise<boolean> => {
+    const event = CampaignEventValidator.parse(rawEvent);
+    const assignments: Record<CampaignEvent, string> = {
+        shown: `state.firstShownAt = coalesce(state.firstShownAt, $now), state.lastShownAt = $now,
+                state.shownCount = coalesce(state.shownCount, 0) + 1`,
+        clicked: 'state.clickedAt = $now',
+        dismissed: 'state.dismissedAt = $now',
+        converted: 'state.convertedAt = $now',
+    };
+    return withCampaignTransaction('campaign:recordEvent', async transaction => {
+        const params = { profileId, campaignId, ...campaignTimeParams() };
+        // A profile lock prevents concurrent devices from creating duplicate state edges
+        // or losing shown increments, without locking the entire campaign audience.
+        const locked = await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
+             WHERE ${liveCampaignPredicate} AND ${campaignAgePredicate}
+             SET p.campaignStateLock = coalesce(p.campaignStateLock, 0) + 1
+             RETURN p.profileId AS profileId`,
+            params
+        );
+        if (!locked.records.length) return false;
+        const result = await transaction.run(
+            `MATCH (p:Profile {profileId: $profileId})-[:IN_CAMPAIGN_AUDIENCE]->(c:Campaign {id: $campaignId})
+             WHERE ${liveCampaignPredicate} AND ${campaignAgePredicate}
+             MERGE (p)-[state:CAMPAIGN_STATE]->(c) SET ${assignments[event]}
+             RETURN state`,
+            params
+        );
+        return result.records.length > 0;
+    });
+};

package/src/accesslayer/campaign/update.ts

@@ -0,0 +1,50 @@
+import { TRPCError } from '@trpc/server';
+import {
+    CampaignValidator,
+    UpdateCampaignInputValidator,
+    type Campaign,
+    type UpdateCampaignInput,
+} from '@learncard/types';
+
+import {
+    assertCampaignEditable,
+    campaignProperties,
+    lockCampaign,
+    withCampaignTransaction,
+} from './shared';
+
+export const updateCampaign = async (input: UpdateCampaignInput): Promise<Campaign> => {
+    const { campaignId, updates } = UpdateCampaignInputValidator.parse(input);
+    return withCampaignTransaction('campaign:update', async transaction => {
+        const existing = await lockCampaign(transaction, campaignId);
+        assertCampaignEditable(existing);
+        const message = updates.message ?? existing.message;
+        const result = CampaignValidator.safeParse({
+            ...existing,
+            ...updates,
+            id: campaignId,
+            message: { ...message, id: campaignId },
+            notification:
+                updates.notification === null
+                    ? undefined
+                    : (updates.notification ?? existing.notification),
+            startsAt:
+                updates.startsAt === null ? undefined : (updates.startsAt ?? existing.startsAt),
+            endsAt: updates.endsAt === null ? undefined : (updates.endsAt ?? existing.endsAt),
+            updatedAt: new Date().toISOString(),
+        });
+        if (!result.success)
+            throw new TRPCError({ code: 'BAD_REQUEST', message: result.error.message });
+        if (existing.status !== 'draft' && result.data.status === 'draft') {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: `Campaign status cannot transition from ${existing.status} to draft`,
+            });
+        }
+        await transaction.run('MATCH (c:Campaign {id: $campaignId}) SET c += $properties', {
+            campaignId,
+            properties: campaignProperties(result.data),
+        });
+        return result.data;
+    });
+};

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/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);