@learncard/network-brain-service 4.0.3 → 4.1.0

package/esbuildPlugins.cjs

@@ -2,6 +2,7 @@ const path = require('node:path');
 const fs = require('node:fs');
 
 const { sentryEsbuildPlugin } = require('@sentry/esbuild-plugin');
+const { withSentryRateLimitRetry } = require('../../../scripts/sentry-rate-limit-retry.cjs');
 
 const forceCjsSodiumWrapperPlugin = {
     name: 'force-cjs-sodium-wrapper',
@@ -40,10 +41,12 @@ const copyDidkitWasmPlugin = {
 module.exports = [
     forceCjsSodiumWrapperPlugin,
     copyDidkitWasmPlugin,
-    sentryEsbuildPlugin({
-        telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
-        authToken: process.env.SENTRY_AUTH_TOKEN,
-        org: process.env.SENTRY_ORG,
-        project: process.env.SENTRY_PROJECT,
-    }),
+    withSentryRateLimitRetry(
+        sentryEsbuildPlugin({
+            telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
+            authToken: process.env.SENTRY_AUTH_TOKEN,
+            org: process.env.SENTRY_ORG,
+            project: process.env.SENTRY_PROJECT,
+        })
+    ),
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-brain-service",
-    "version": "4.0.3",
+    "version": "4.1.0",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -15,6 +15,7 @@
         "test:watch": "vitest --config vitest.config.ts",
         "test:coverage": "vitest run --coverage --config vitest.config.ts",
         "test:integration": "vitest run --config vitest.integration.config.ts",
+        "test:campaigns": "vitest run --config vitest.campaigns.config.ts",
         "test:inbox:e2e": "vitest run --config vitest.inbox-e2e.config.ts",
         "test:profile-search": "vitest run --config vitest.profile-search-neo4j.config.ts",
         "test:integration:watch": "vitest --config vitest.integration.config.ts",
@@ -23,6 +24,7 @@
         "seed:dev-app": "bun scripts/seed-dev-app.ts",
         "seed:demo-persona": "bun --conditions=development scripts/seed-demo-persona.ts",
         "skill-frameworks": "bun scripts/skill-frameworks.ts",
+        "skill-embeddings:backfill": "bun --conditions=development scripts/skill-embeddings-backfill.ts",
         "backfill:profile-search": "bun scripts/backfill-profile-search.ts",
         "build": "shx rm -rf dist && node bundle.mjs && tsc --p tsconfig.build.json && tsc --showConfig --p tsconfig.build.json > tsconfig.temp.json && tsc-alias --replacer ./tsc-alias-replacer.cjs -p tsconfig.temp.json && shx rm tsconfig.temp.json",
         "typecheck": "tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p tsconfig.entrypoints.json",
@@ -61,27 +63,28 @@
         "testcontainers": "^9.1.1"
     },
     "dependencies": {
+        "@aws-sdk/client-bedrock-runtime": "^3.1139.0",
         "@aws-sdk/client-sqs": "^3.379.1",
         "@digitalcredentials/issuer-registry-client": "^4.1.0",
         "@fastify/cors": "^11.2.0",
         "@google/genai": "^1.27.0",
-        "@learncard/credential-library": "2.1.2",
-        "@learncard/core": "9.4.39",
-        "@learncard/crypto-plugin": "1.1.39",
-        "@learncard/did-web-plugin": "1.1.39",
-        "@learncard/didkey-plugin": "1.1.39",
-        "@learncard/didkit-plugin": "1.10.4",
-        "@learncard/didkit-plugin-node": "0.3.4",
-        "@learncard/dynamic-loader-plugin": "1.1.39",
-        "@learncard/encryption-plugin": "1.1.39",
-        "@learncard/expiration-plugin": "1.2.39",
+        "@learncard/credential-library": "2.1.4",
+        "@learncard/core": "9.4.41",
+        "@learncard/crypto-plugin": "1.1.41",
+        "@learncard/did-web-plugin": "1.1.41",
+        "@learncard/didkey-plugin": "1.1.41",
+        "@learncard/didkit-plugin": "1.10.6",
+        "@learncard/didkit-plugin-node": "0.3.6",
+        "@learncard/dynamic-loader-plugin": "1.1.41",
+        "@learncard/encryption-plugin": "1.1.41",
+        "@learncard/expiration-plugin": "1.2.41",
         "@learncard/email-templates": "1.2.1",
-        "@learncard/helpers": "1.6.3",
-        "@learncard/learn-card-plugin": "1.2.39",
+        "@learncard/helpers": "1.7.1",
+        "@learncard/learn-card-plugin": "1.2.41",
         "@learncard/partner-connect-core": "0.2.0",
-        "@learncard/types": "5.23.1",
-        "@learncard/vc-plugin": "1.6.5",
-        "@learncard/vc-templates-plugin": "1.1.39",
+        "@learncard/types": "5.24.0",
+        "@learncard/vc-plugin": "1.6.7",
+        "@learncard/vc-templates-plugin": "1.1.41",
         "@sentry/serverless": "7.61.0",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",
@@ -114,7 +117,7 @@
         "undici": "^6",
         "tweetnacl": "^1.0.3",
         "uuid": "^14.0.0",
-        "zod": "4.4.3",
+        "zod": "4.6.6",
         "zod-openapi": "^5.0.1"
     },
     "repository": {

package/project.json

@@ -127,6 +127,20 @@
                 "script": "test:integration"
             }
         },
+        "test:campaigns": {
+            "executor": "nx:run-script",
+            "cache": false,
+            "dependsOn": ["^build"],
+            "inputs": [
+                "source",
+                "tests",
+                "{projectRoot}/vitest.campaigns.config.ts",
+                "{projectRoot}/test-setup.ts"
+            ],
+            "options": {
+                "script": "test:campaigns"
+            }
+        },
         "test:boost-recipients": {
             "executor": "nx:run-script",
             "cache": false,

package/scripts/skill-embeddings-backfill.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env bun
+/**
+ * LC-2206 operator backfill: (re-)embed every Skill with the configured Nova 2 generation.
+ *
+ *   bun run skill-embeddings:backfill                      # dry run: counts only, no Bedrock calls
+ *   bun run skill-embeddings:backfill --apply --target <neo4j-host> [--max N] [--page-size N] [--cursor <skillId>]
+ *
+ * - Dry run is the default and never calls Bedrock or writes to Neo4j.
+ * - --apply requires SKILL_EMBEDDING_BEDROCK_ENABLED=true and --target equal to the host in
+ *   NEO4J_URI, so a copied shell cannot silently write to the wrong database.
+ * - Takes the same Redis lease as the startup backfill (one writer per generation).
+ * - Idempotent and resumable: skills whose stored key matches sha256(identity + text) are
+ *   skipped; on early stop it prints the cursor to resume from.
+ *
+ * Writes only the Nova property; the legacy Google `s.embedding` and the read flag
+ * (SKILL_EMBEDDING_BEDROCK_READ_ENABLED) are untouched, so it is safe while search reads legacy.
+ *
+ * Uses the normal AWS credential chain (SigV4). Paid: each embedded skill is one InvokeModel.
+ */
+import { environment } from '@environment';
+import {
+    acquireSkillEmbeddingBackfillLock,
+    buildSkillEmbeddingText,
+    getSkillEmbeddingGeneration,
+    isSkillEmbeddingEnabled,
+    runSkillEmbeddingBackfill,
+    skillNeedsEmbedding,
+} from '@helpers/skill-embedding.helpers';
+import { getSkillEmbeddingCandidates } from '@accesslayer/skill/read';
+import { neogma } from '@instance';
+
+// Public list price snapshot checked by AI Passport on 2026-10-13 (us-east-1, on-demand text).
+const NOVA2_USD_PER_MILLION_INPUT_TOKENS = 0.135;
+// Planning assumption only; Nova responses carry no token usage.
+const ASSUMED_CHARS_PER_TOKEN = 4;
+
+type Options = {
+    apply: boolean;
+    target?: string;
+    max?: number;
+    pageSize: number;
+    cursor: string | null;
+};
+
+const parseArgs = (argv: string[]): Options => {
+    const options: Options = { apply: false, pageSize: 100, cursor: null };
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = () => {
+            const value = argv[i + 1];
+            if (!value) throw new Error(`${arg} needs a value`);
+            i += 1;
+            return value;
+        };
+
+        if (arg === '--apply') options.apply = true;
+        else if (arg === '--target') options.target = next();
+        else if (arg === '--max') options.max = Number(next());
+        else if (arg === '--page-size') options.pageSize = Number(next());
+        else if (arg === '--cursor') options.cursor = next();
+        else throw new Error(`Unknown argument ${arg}`);
+    }
+
+    return options;
+};
+
+const neo4jHost = (): string => {
+    try {
+        return new URL(environment.NEO4J_URI).hostname;
+    } catch {
+        return environment.NEO4J_URI;
+    }
+};
+
+const estimate = async (pageSize: number) => {
+    const generation = getSkillEmbeddingGeneration();
+    let cursor: string | null = null;
+    let total = 0;
+    let needed = 0;
+    let chars = 0;
+
+    while (true) {
+        const page = await getSkillEmbeddingCandidates(generation, pageSize, cursor);
+        for (const candidate of page.records) {
+            total += 1;
+            if (skillNeedsEmbedding(candidate, generation)) {
+                needed += 1;
+                chars += buildSkillEmbeddingText(candidate).length;
+            }
+        }
+        if (!page.cursor) break;
+        cursor = page.cursor;
+    }
+
+    const tokens = Math.ceil(chars / ASSUMED_CHARS_PER_TOKEN);
+    return {
+        generation: generation.identity,
+        vectorProperty: generation.vectorProperty,
+        indexName: generation.indexName,
+        totalSkills: total,
+        needEmbedding: needed,
+        textChars: chars,
+        estimatedTokens: tokens,
+        estimatedUsd: Number(
+            ((tokens / 1_000_000) * NOVA2_USD_PER_MILLION_INPUT_TOKENS).toFixed(4)
+        ),
+        invokeModelCalls: needed,
+    };
+};
+
+const main = async () => {
+    const options = parseArgs(process.argv.slice(2));
+
+    console.info(`Neo4j host: ${neo4jHost()}`);
+    console.info('Dry-run estimate:', await estimate(options.pageSize));
+
+    if (!options.apply) {
+        console.info('Dry run only. Re-run with --apply --target <neo4j-host> to embed.');
+        return;
+    }
+
+    if (!isSkillEmbeddingEnabled()) throw new Error('SKILL_EMBEDDING_BEDROCK_ENABLED must be true');
+    if (options.target !== neo4jHost()) {
+        throw new Error('--target must equal the NEO4J_URI host; refusing to write');
+    }
+
+    const lock = await acquireSkillEmbeddingBackfillLock();
+    if (!lock) throw new Error('Another skill embedding backfill holds the lock');
+
+    try {
+        const stats = await runSkillEmbeddingBackfill(
+            {
+                pageSize: options.pageSize,
+                maxEmbeddings: options.max,
+                cursor: options.cursor,
+            },
+            { keepAlive: lock.keepAlive }
+        );
+
+        console.info('Backfill result:', stats);
+        if (stats.stoppedReason) {
+            console.info(
+                `Stopped early (${stats.stoppedReason}). Resume with --cursor ${stats.cursor ?? ''}`
+            );
+            process.exitCode = 2;
+        }
+    } finally {
+        await lock.release();
+    }
+};
+
+main()
+    .catch(error => {
+        console.error(error instanceof Error ? error.message : 'Backfill failed');
+        process.exitCode = 1;
+    })
+    .finally(async () => {
+        await neogma.driver.close();
+        process.exit();
+    });

package/serverless-local.yml

@@ -62,6 +62,10 @@ provider:
         REDIS_PORT:
             'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Port]
         NOTIFICATIONS_QUEUE_URL: ${construct:notifications-queue.queueUrl}
+        SKILL_EMBEDDING_BEDROCK_ENABLED: ${env:SKILL_EMBEDDING_BEDROCK_ENABLED, "false"}
+        SKILL_EMBEDDING_BEDROCK_MODEL_ID: ${env:SKILL_EMBEDDING_BEDROCK_MODEL_ID, "amazon.nova-2-multimodal-embeddings-v1:0"}
+        SKILL_EMBEDDING_DIMENSION: ${env:SKILL_EMBEDDING_DIMENSION, "1024"}
+        SKILL_EMBEDDING_BEDROCK_READ_ENABLED: ${env:SKILL_EMBEDDING_BEDROCK_READ_ENABLED, "false"}
         SKILL_EMBEDDING_GOOGLE_API_KEY: ${env:SKILL_EMBEDDING_GOOGLE_API_KEY, ""}
         SKILL_EMBEDDING_BATCH_SIZE: ${env:SKILL_EMBEDDING_BATCH_SIZE, "25"}
         SKILL_EMBEDDING_BACKFILL_ON_STARTUP: ${env:SKILL_EMBEDDING_BACKFILL_ON_STARTUP, "false"}

package/serverless.function-env.cjs

@@ -14,6 +14,8 @@ const PROVIDER_SECRETS = [
     'MESSAGEBIRD_AUTH_TOKEN',
     'SENTRY_DSN',
     'POSTHOG_API_KEY',
+    // LC-2206: legacy Google skill-search read and legacy vector writes; remove after the
+    // Nova read flag has been on for the rollback window.
     'SKILL_EMBEDDING_GOOGLE_API_KEY',
     'SKILLS_PROVIDER_API_KEY',
     'TWILIO_ACCOUNT_SID',
@@ -24,6 +26,7 @@ const PROVIDER_SECRETS = [
     'CREDENTIAL_REFRESH_DIGEST_SECRET',
     'SHARE_LINK_REQUEST_HASH_SECRET',
     'APP_STORE_ADMIN_PROFILE_IDS',
+    'CAMPAIGN_ADMIN_PROFILE_IDS',
     'LOGIN_PROVIDER_DID',
     'NOTIFICATIONS_SERVICE_WEBHOOK_URL',
 ];

package/serverless.local.yml

@@ -53,6 +53,10 @@ provider:
         NEO4J_URI: ${env:NEO4J_URI}
         NEO4J_USERNAME: ${env:NEO4J_USERNAME}
         NEO4J_PASSWORD: ${env:NEO4J_PASSWORD}
+        SKILL_EMBEDDING_BEDROCK_ENABLED: ${env:SKILL_EMBEDDING_BEDROCK_ENABLED, "false"}
+        SKILL_EMBEDDING_BEDROCK_MODEL_ID: ${env:SKILL_EMBEDDING_BEDROCK_MODEL_ID, "amazon.nova-2-multimodal-embeddings-v1:0"}
+        SKILL_EMBEDDING_DIMENSION: ${env:SKILL_EMBEDDING_DIMENSION, "1024"}
+        SKILL_EMBEDDING_BEDROCK_READ_ENABLED: ${env:SKILL_EMBEDDING_BEDROCK_READ_ENABLED, "false"}
         SKILL_EMBEDDING_GOOGLE_API_KEY: ${env:SKILL_EMBEDDING_GOOGLE_API_KEY, ""}
         SKILL_EMBEDDING_GOOGLE_MODEL: ${env:SKILL_EMBEDDING_GOOGLE_MODEL, "gemini-embedding-001"}
         SKILL_EMBEDDING_BATCH_SIZE: ${env:SKILL_EMBEDDING_BATCH_SIZE, "25"}

package/serverless.yml

@@ -141,7 +141,8 @@ provider:
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
     # Every function shares the default execution role. Grant it read access to the stage's
-    # runtime-secrets bundle only; the id itself is passed through RUNTIME_SECRETS_ID.
+    # runtime-secrets bundle only; the id itself is passed through RUNTIME_SECRETS_ID. It may
+    # also invoke the Nova 2 embeddings model used for skill matching (LC-2206).
     iam:
         role:
             statements:
@@ -149,6 +150,16 @@ provider:
                   Action: secretsmanager:GetSecretValue
                   Resource:
                       Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:brain-service/${sls:stage}/runtime-secrets-*
+                # LC-2206: skill-matching embeddings. InvokeModel on the one reviewed Nova 2
+                # embeddings foundation model, in-Region us-east-1 only (the model has no geo or
+                # global inference profile). SigV4 with this role; no Bedrock API keys
+                # (bedrock:CallWithBearerToken) are granted. Keep in sync with
+                # DEPLOYED_SKILL_EMBEDDING_ALLOWLIST in src/config/skillEmbedding.ts.
+                - Sid: SkillEmbeddingNova2Invoke
+                  Effect: Allow
+                  Action: bedrock:InvokeModel
+                  Resource:
+                      Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1::foundation-model/amazon.nova-2-multimodal-embeddings-v1:0
     # Bundle mode emits only infra (Redis/queue CF intrinsics, the bundle pointer and the
     # deploy commit); fallback mode retains the existing GitHub credential secrets. Non-secret
     # per-stage tuning, allowlists and OIDC/share-link config are applied from checked-in stage

package/src/accesslayer/campaign/README.md

@@ -0,0 +1,174 @@
+# Campaigns: setup, audiences and engagement (LC-2265)
+
+This slice stores campaign definitions, server-selected audiences and shared engagement
+state. It does not deliver notifications or render messages. LC-2266 owns dispatch and
+`sendTestToMe`; LC-2267 owns app integration. It does not require the in-app messages V2
+branches: `message` uses the shared `InAppMessage` schema available in this checkout.
+
+## Administration and lifecycle
+
+Configure `CAMPAIGN_ADMIN_PROFILE_IDS` as a private, comma-separated profile allowlist.
+It is empty by default. Every management operation requires both an allowlisted profile
+and the `campaigns:admin` scope (or `*:*`). The authenticated `isAdmin` discovery query
+returns a boolean, like App Store administration; it exposes no campaigns or audiences.
+User queries need `campaigns:read`, and enrollment/events need `campaigns:write`.
+SDK API tokens also need `profiles:read` for the plugin's profile check.
+
+```ts
+// `client` is an authenticated brain-client; campaignAdmin is allowlisted.
+const campaign = await client.campaigns.create.mutate({
+    id: 'transcript-pilot-v1',
+    name: 'Transcript pilot',
+    channels: ['inApp'],
+    message: { title: 'Explore your next step', frequency: 'once' },
+});
+await client.campaigns.setStatus.mutate({ campaignId: campaign.id, status: 'live' });
+```
+
+IDs are immutable, lowercase `[a-z0-9-]{3,64}`, unique, and always replace `message.id`.
+Creation defaults to `draft`, `excludeMinors: true`, `selfEnroll: false`. Supported statuses
+are `draft`, `live`, `paused`, `archived`; archived campaigns cannot be edited or have
+audience members added. Only drafts and archived campaigns can be deleted: archive a live or paused
+campaign first. Live and paused campaigns cannot transition back to draft. Admin deletion removes
+the campaign and its relationships.
+Use a new ID for a new campaign; deleting/reusing an ID cannot clear clients' local seen state.
+
+`channels` must contain `inApp`, `notify`, or both without duplicates. `notify` requires
+`notification: { title, body }`, but does not send anything in this slice. Dates are ISO
+timestamps normalized to UTC; `startsAt` is inclusive and `endsAt` is exclusive. If both
+exist, the end must follow the start. Partial updates preserve omitted fields; `null`
+clears optional notification/start/end fields. Updates replace `message` as a whole.
+
+## Audience sources
+
+Preview is read-only. Adding an audience merges distinct profiles and preserves the first
+membership's `addedAt` and `source`, including `selfEnrolled`. Both calls return
+`{ count }`: the number of eligible matching profiles, **not** the number of new edges.
+Overlapping or repeated additions therefore return their matched count without duplicating
+membership. These are snapshots, not subscriptions to later credential claims/revocations.
+
+```ts
+import type { CampaignAudienceSource } from '@learncard/types';
+
+const campaignId = 'transcript-pilot-v1';
+const sources: CampaignAudienceSource[] = [
+    { type: 'dids', dids: ['did:key:example'] },
+    { type: 'emails', emails: ['learner@example.org'] },
+    {
+        type: 'credentialsSentBy',
+        senderProfileId: 'university-transcripts',
+        metadata: { kind: 'transcript' },
+        since: '2026-01-01T00:00:00Z',
+        includePending: false,
+    },
+    {
+        type: 'credentialsSentBy',
+        listingId: 'university-transcript-app',
+        metadata: { kind: 'transcript' },
+        includePending: false,
+    },
+    { type: 'inboxClaims', issuerDid: 'did:key:issuer', since: '2026-01-01T00:00:00Z' },
+    {
+        type: 'boostRecipients',
+        boostUri: 'lc:network:network.example.org/trpc:boost:example',
+        includePending: false,
+    },
+];
+
+for (const source of sources) {
+    const preview = await client.campaigns.previewAudience.query({ campaignId, source });
+    // Review preview.count before adding. Counts can change if source data changes.
+    await client.campaigns.addAudience.mutate({ campaignId, source });
+}
+const page = await client.campaigns.pageAudience.query({ campaignId, limit: 100 });
+// Next request: { campaignId, limit: 100, cursor: page.cursor }, while page.hasMore.
+```
+
+- DID/email lists accept 1–1000 entries per call. DIDs match stored DIDs or this network's
+  canonically encoded `did:web:<domain>:users:<profileId>` alias. Emails are trimmed/lowercased
+  and only verified contact methods qualify; the profile's display email is not used.
+- `credentialsSentBy` requires exactly one sender profile or listing. All metadata entries
+  must match exactly on `CREDENTIAL_SENT.metadata.*`; `since` filters the send date. Metadata is
+  limited to 20 keys, with values of at most 2048 characters.
+  Keys are validated and values are bound parameters, never interpolated into Cypher.
+- `inboxClaims` matches the stored issuer DID and filters the **claim** timestamp.
+- Boost URIs must identify a boost on this network. Credential sources exclude revoked
+  sends/receipts even with `includePending: true`. Unaccepted sends and pending receipts
+  only qualify when that option is true. Recipient matching uses each send's `to` profile.
+- Paging uses ascending profile IDs and reapplies the campaign's current minor policy.
+  `getStats().audience` counts stored membership, which may exceed currently eligible paging
+  results if the profile or campaign age policy changes.
+
+Issuers should use a **dedicated sending profile or listing** for transcripts and attach
+`metadata: { kind: 'transcript' }` when calling `sendCredential`. The server cannot inspect
+encrypted credential contents; a metadata label is not proof of CLR type or ownership.
+
+## Two-layer targeting and self-enrollment
+
+The server narrows the audience from visible metadata. In the later app-integration slice,
+the device must still confirm a rule such as issuer X **and** `vcTypes: ['ClrCredential']`
+on the same credential before displaying the campaign. This backend does not import the
+V2 targeting engine, evaluate those rules, or send decrypted credentials to the server.
+
+`getMyCampaigns` returns live, in-window, enabled `inApp` campaigns for audience members,
+plus eligible campaigns with `selfEnroll: true`, joined to the caller's engagement state.
+Malformed legacy campaign definitions are logged and skipped per record so one bad campaign cannot
+break discovery for every profile.
+Discoverability is not enrollment: `recordEvent` is a no-op until membership exists.
+After a local match, the client can call `enroll({ campaignId })`. Enrollment requires a
+live, in-window, enabled `inApp` campaign with self-enrollment enabled and is idempotent.
+Only profiles with a known adult birthday can self-enroll, even when the campaign has
+`excludeMinors: false`.
+
+**Privacy disclosure:** enrollment tells the server only that this profile matched a
+campaign. That membership can itself reveal sensitive information. Authors must write
+rules that reveal no more than needed. No credential content or targeting evidence is
+accepted by the enrollment/event endpoints, and campaign routes disable Sentry input capture.
+
+**Product/legal sign-off is still required for the age policy.** The implemented policy
+excludes missing, empty, and non-date-format birthdays from every audience, including when
+`excludeMinors: false`. It also excludes `type: 'child'`, guardian-managed human profiles, and
+known under-18 birthdays when `excludeMinors` is enabled. Managed service/organization profiles
+remain age-exempt unless explicitly typed as a child. Age uses UTC calendar dates; a Feb 29 birthday
+reaches the cutoff on March 1 in a non-leap year. No policy approval or production rollout is implied
+by this PR.
+
+## Engagement and SDK
+
+`recordEvent({ campaignId, event })` accepts `shown`, `clicked`, `dismissed`, `converted`.
+It returns `false` without profile-lock or engagement writes for missing campaigns, nonmembers,
+age-ineligible profiles, and campaigns that are not currently live and in-window.
+`shown` sets `firstShownAt` once, updates `lastShownAt`, and increments `shownCount`.
+Other events store their latest timestamp. Per-profile transactional locking prevents
+duplicate state edges and lost increments under concurrent devices. Repeated requests
+are separate events, not transport-idempotent retries.
+
+Stats count distinct profiles, not impressions; `enrolled` counts memberships originally
+created by self-enrollment. `notified` is reserved for LC-2266 and is not client-writable.
+All user/discovery calls share a 60-call/profile/minute rate limit; admin operations do not.
+
+The network plugin exposes `learnCard.invoke.getMyCampaigns()`,
+`recordCampaignEvent(campaignId, event)`, `enrollInCampaign(campaignId)`, and the admin
+methods `campaignsIsAdmin`, `campaignsCreate`, `campaignsUpdate`, `campaignsGet`,
+`campaignsList`, `campaignsDelete`, `campaignsSetStatus`, `campaignsPreviewAudience`,
+`campaignsAddAudience`, `campaignsPageAudience`, `campaignsGetStats`. The brain-client
+derives these routes from `AppRouter`; there is no separate hand-written client schema.
+
+## Verification
+
+```bash
+cd services/learn-card-network/brain-service
+bun run test:campaigns
+```
+
+This starts a disposable Neo4j testcontainer, uses synthetic accounts/configuration, and
+does not read the developer's database. Docker is required. The suite covers all source
+types, permissions, injection rejection, minor rules, paging, lifecycle, enrollment and
+concurrent shared state. Schema tests live in `@learncard/types`; SDK forwarding tests
+live in `@learncard/network-plugin`. Hosted CI runs the Neo4j suite separately from the
+service's default unit suite. No app UI, notification delivery or device QA is claimed.
+
+The hosted Linux verification workflow also runs `test/verification/campaigns.ts` via
+`lc verify script` after the full catalog: real signed SDK calls prove non-admin denial
+and user isolation over HTTP. The default stack grants no admin access, so positive
+administration and graph mutations are covered by the dedicated Neo4j suite instead.