@learncard/network-brain-service 3.19.1 → 4.0.1

package/src/accesslayer/share-link/reserve.ts

@@ -7,10 +7,12 @@ import {
     DEFAULT_SHARE_LINK_POLICY,
     type ShareLinkPolicySnapshot,
 } from '@helpers/share-link-policy/types';
+import { mergeShareLinkPolicyConservatively } from '@helpers/share-link-policy/resolver';
 
 import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
 import type { ShareLinkRecord } from '../../models/ShareLink';
 import { failShareLink } from './errors';
+import { pinShareAttachment, queueShareAttachmentCleanup } from './attachment';
 import {
     deleteReservation,
     enqueueCleanupJob,
@@ -21,6 +23,7 @@ import {
     readOperation,
     readReservation,
     readShareById,
+    toShareLinkOperationPolicy,
     toShareLinkOperationRecord,
     toShareLinkRecord,
     toShareLinkReservationRecord,
@@ -60,6 +63,8 @@ const parseRecordedResult = (
 };
 
 type ReservationProps = {
+    attachmentId?: string | null;
+    attachmentChunkCount?: number | null;
     shareId: string;
     namespace: string;
     ownerProfileId: string;
@@ -96,6 +101,20 @@ const writeReservation = async (
     tx: ShareLinkTransaction,
     props: ReservationProps
 ): Promise<void> => {
+    if (props.contentVersion !== null && props.attachmentId && props.attachmentChunkCount) {
+        await pinShareAttachment(
+            tx,
+            {
+                namespace: props.namespace,
+                ownerProfileId: props.ownerProfileId,
+                shareId: props.shareId,
+                contentVersion: props.contentVersion,
+                attachmentId: props.attachmentId,
+                chunkCount: props.attachmentChunkCount,
+            },
+            props.requestHash
+        );
+    }
     await tx.run('CREATE (r:ShareLinkReservation) SET r = $props', { props });
 };
 
@@ -120,9 +139,30 @@ const bumpShareGeneration = async (
 const supersedeReservation = async (
     tx: ShareLinkTransaction,
     reservationProps: Record<string, unknown>,
-    now: string
+    now: string,
+    retainAttachment = false
 ): Promise<ShareLinkReservationRecord> => {
     const reservation = toShareLinkReservationRecord(reservationProps);
+    if (
+        !retainAttachment &&
+        reservation.attachmentId &&
+        reservation.attachmentChunkCount &&
+        reservation.contentVersion
+    ) {
+        await queueShareAttachmentCleanup(
+            tx,
+            {
+                namespace: reservation.namespace,
+                ownerProfileId: reservation.ownerProfileId,
+                shareId: reservation.shareId,
+                contentVersion: reservation.contentVersion,
+                attachmentId: reservation.attachmentId,
+                chunkCount: reservation.attachmentChunkCount,
+            },
+            'abandoned',
+            now
+        );
+    }
 
     if (reservation.objectRef) {
         await enqueueCleanupJob(tx, {
@@ -214,6 +254,7 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
                 };
             }
 
+            let retryPolicy = toShareLinkOperationPolicy(existingOperation);
             const existingReservationProps = await readReservation(tx, input.shareId);
 
             if (existingReservationProps) {
@@ -230,6 +271,10 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
                     );
                 }
 
+                retryPolicy = retryPolicy
+                    ? mergeShareLinkPolicyConservatively(retryPolicy, existingReservation.policy)
+                    : existingReservation.policy;
+
                 if (isLeaseActive(existingReservation.leaseExpiresAt, now)) {
                     if (!share) {
                         failShareLink('CONFLICT', 'in-flight reservation exists without a share');
@@ -245,7 +290,7 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
 
                 // Same logical operation, expired lease: retain its expiry.
                 supersededExpiresAt = { value: existingReservation.expiresAt };
-                await supersedeReservation(tx, existingReservationProps, nowIso);
+                await supersedeReservation(tx, existingReservationProps, nowIso, true);
             }
 
             if (!share) {
@@ -255,6 +300,10 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
                 failShareLink('CONFLICT', 'cannot re-drive create for a stopped share');
             }
 
+            const policy = mergeShareLinkPolicyConservatively(
+                retryPolicy ?? DEFAULT_SHARE_LINK_POLICY,
+                input.policy ?? retryPolicy ?? DEFAULT_SHARE_LINK_POLICY
+            );
             return createReservationForShare(tx, {
                 share,
                 opKey,
@@ -264,14 +313,17 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
                 contentVersion: 1,
                 baseContentVersion: share.contentVersion,
                 content: input.content,
+                attachment: input.attachment,
                 selectedCount: input.selectedCount,
                 title: input.title,
                 note: input.note ?? null,
                 expiresAt:
                     supersededExpiresAt !== null ? supersededExpiresAt.value : share.expiresAt,
                 passcodeHash: share.passcodeHash ?? input.passcodeHash ?? null,
-                notifyOnView: share.notifyOnView ?? input.notifyOnView ?? false,
-                policy: input.policy ?? DEFAULT_SHARE_LINK_POLICY,
+                notifyOnView:
+                    (share.notifyOnView ?? input.notifyOnView ?? false) &&
+                    policy.viewCountingEnabled,
+                policy,
                 leaseOwner: input.leaseOwner,
                 leaseExpiresAt,
                 nowIso,
@@ -335,6 +387,7 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
             operationId,
             shareId: input.shareId,
             requestHash: input.requestHash,
+            policy,
             now: nowIso,
             pruneAfter,
         });
@@ -349,6 +402,8 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
             objectRef,
             contentVersion: 1,
             baseVersion: 1,
+            attachmentId: input.attachment?.id ?? null,
+            attachmentChunkCount: input.attachment?.chunkCount ?? null,
             baseContentVersion: 1,
             contentHash: input.content.contentHash,
             contentBytes: input.content.contentBytes,
@@ -388,6 +443,7 @@ export const reserveCreate = async (input: ReserveCreateInput): Promise<ReserveS
 };
 
 type CreateReservationForShareInput = {
+    attachment?: import('@learncard/types').ShareLinkAttachment;
     share: ShareLinkRecord;
     opKey: ShareLinkOperationKey;
     operationId: string;
@@ -420,6 +476,7 @@ const createReservationForShare = async (
         operationId: input.operationId,
         shareId: input.share.id,
         requestHash: input.requestHash,
+        policy: input.policy,
         now: input.nowIso,
         pruneAfter: input.pruneAfter,
     });
@@ -434,6 +491,14 @@ const createReservationForShare = async (
         operationId: input.operationId,
         objectRef: input.objectRef,
         contentVersion: input.contentVersion,
+        attachmentId:
+            input.contentVersion !== null
+                ? (input.attachment?.id ?? null)
+                : (input.share.attachmentId ?? null),
+        attachmentChunkCount:
+            input.contentVersion !== null
+                ? (input.attachment?.chunkCount ?? null)
+                : (input.share.attachmentChunkCount ?? null),
         baseVersion: input.share.version,
         baseContentVersion: input.baseContentVersion,
         contentHash: input.content ? input.content.contentHash : null,
@@ -539,6 +604,7 @@ export const reserveReplacement = async (
                 };
             }
 
+            let retryPolicy = toShareLinkOperationPolicy(existingOperation);
             const existingReservationProps = await readReservation(tx, input.shareId);
 
             if (existingReservationProps) {
@@ -555,6 +621,10 @@ export const reserveReplacement = async (
                     );
                 }
 
+                retryPolicy = retryPolicy
+                    ? mergeShareLinkPolicyConservatively(retryPolicy, existingReservation.policy)
+                    : existingReservation.policy;
+
                 if (isLeaseActive(existingReservation.leaseExpiresAt, now)) {
                     return {
                         outcome: 'reserved',
@@ -564,12 +634,20 @@ export const reserveReplacement = async (
                     };
                 }
 
-                await supersedeReservation(tx, existingReservationProps, nowIso);
+                await supersedeReservation(tx, existingReservationProps, nowIso, true);
             }
 
             return reserveReplacementForLockedShare(tx, {
                 share,
-                input,
+                input: {
+                    ...input,
+                    // The ceiling belongs to the logical request, not its lease.
+                    // Missing legacy state fails closed after reservation cleanup.
+                    policy: mergeShareLinkPolicyConservatively(
+                        retryPolicy ?? DEFAULT_SHARE_LINK_POLICY,
+                        input.policy ?? retryPolicy ?? DEFAULT_SHARE_LINK_POLICY
+                    ),
+                },
                 opKey,
                 leaseExpiresAt,
                 nowIso,
@@ -659,6 +737,7 @@ const reserveReplacementForLockedShare = async (
         contentVersion: input.content ? input.content.contentVersion : null,
         baseContentVersion: share.contentVersion,
         content: input.content,
+        attachment: input.content?.attachment,
         selectedCount: input.content ? input.content.selectedCount : share.selectedCount,
         title: input.title ?? share.title,
         note: input.note !== undefined ? input.note : share.note,

package/src/accesslayer/share-link/revoke.ts

@@ -2,6 +2,7 @@ import { SHARE_LINK_OPERATION_RETENTION_MS } from '@helpers/share-link-lifecycle
 
 import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
 import { failShareLink } from './errors';
+import { queueShareAttachmentCleanup } from './attachment';
 import {
     deleteReservation,
     enqueueCleanupJob,
@@ -105,6 +106,25 @@ export const revokeShareLink = async (
 
         if (reservationProps) {
             const reservation = toShareLinkReservationRecord(reservationProps);
+            if (
+                reservation.attachmentId &&
+                reservation.attachmentChunkCount &&
+                reservation.contentVersion
+            ) {
+                await queueShareAttachmentCleanup(
+                    tx,
+                    {
+                        namespace: reservation.namespace,
+                        ownerProfileId: reservation.ownerProfileId,
+                        shareId: reservation.shareId,
+                        contentVersion: reservation.contentVersion,
+                        attachmentId: reservation.attachmentId,
+                        chunkCount: reservation.attachmentChunkCount,
+                    },
+                    'abandoned',
+                    nowIso
+                );
+            }
 
             if (reservation.objectRef) {
                 await enqueueCleanupJob(tx, {
@@ -131,6 +151,21 @@ export const revokeShareLink = async (
         }
 
         if (share.activeObjectRef) {
+            if (share.attachmentId && share.attachmentChunkCount) {
+                await queueShareAttachmentCleanup(
+                    tx,
+                    {
+                        namespace: share.namespace,
+                        ownerProfileId: share.ownerProfileId,
+                        shareId: share.id,
+                        contentVersion: share.contentVersion,
+                        attachmentId: share.attachmentId,
+                        chunkCount: share.attachmentChunkCount,
+                    },
+                    'stopped',
+                    nowIso
+                );
+            }
             await enqueueCleanupJob(tx, {
                 objectRef: share.activeObjectRef,
                 operationId: share.activeObjectOperationId!,

package/src/accesslayer/share-link/types.ts

@@ -3,10 +3,10 @@ import type {
     ShareContentCleanupStatus,
     ShareLinkOperationKind,
 } from '@helpers/share-link-lifecycle';
-import type { ShareLinkPolicySnapshot } from '@helpers/share-link-policy';
+import type { CurrentShareLinkPolicy, ShareLinkPolicySnapshot } from '@helpers/share-link-policy';
 
 import type { ShareContentState, ShareLinkRecord, ShareLinkStatus } from '../../models/ShareLink';
-import type { ShareLinkTransactionOptions } from './transaction';
+import type { ShareLinkTransaction, ShareLinkTransactionOptions } from './transaction';
 
 /** Namespace + owner + share id binding used by every lifecycle operation. */
 export type ShareLinkKey = {
@@ -55,6 +55,8 @@ export type ShareLinkOperationRecord = {
  * a bounded lease so a restart can either resume or supersede it.
  */
 export type ShareLinkReservationRecord = {
+    attachmentId?: string | null;
+    attachmentChunkCount?: number | null;
     shareId: string;
     namespace: string;
     ownerProfileId: string;
@@ -122,6 +124,7 @@ export type ShareContentBinding = {
 };
 
 export type ReserveCreateInput = {
+    attachment?: import('@learncard/types').ShareLinkAttachment;
     namespace: string;
     ownerProfileId: string;
     clientRequestId: string;
@@ -143,6 +146,7 @@ export type ReserveCreateInput = {
 };
 
 export type ReserveReplacementContent = ShareContentBinding & {
+    attachment?: import('@learncard/types').ShareLinkAttachment;
     /** Must equal the current visible content version + 1. */
     contentVersion: number;
     selectedCount: number;
@@ -194,6 +198,7 @@ export type ReserveShareLinkResult =
       };
 
 export type FinalizeReservationInput = {
+    verifiedAttachmentId?: string;
     namespace: string;
     ownerProfileId: string;
     shareId: string;
@@ -210,10 +215,10 @@ export type FinalizeReservationInput = {
     verifiedContentHash?: string;
     /** Production-only graph-local policy recheck under the share write lock. */
     resolveCurrentPolicy?: (
-        tx: import('./transaction').ShareLinkTransaction,
+        tx: ShareLinkTransaction,
         ownerProfileId: string,
         now: Date
-    ) => Promise<import('@helpers/share-link-policy/types').ShareLinkPolicySnapshot>;
+    ) => Promise<CurrentShareLinkPolicy>;
     now?: Date;
     /** Maintenance-only: bounded transaction timeout for this unit. */
     transactionTimeoutMs?: number;

package/src/cache/app-store.caches.ts

@@ -3,6 +3,7 @@ import { readAppStoreListingById } from '@accesslayer/app-store-listing/read';
 import {
     getIntegrationForListing,
     getBoostForListingByTemplateAlias,
+    getConsentContractForListingByScopeHash,
 } from '@accesslayer/app-store-listing/relationships/read';
 import { getOwnerProfileForIntegration } from '@accesslayer/integration/relationships/read';
 import {
@@ -28,6 +29,7 @@ const LISTING_CACHE_TTL_MS = 30_000;
 const INTEGRATION_CACHE_TTL_MS = 30_000;
 const OWNER_CACHE_TTL_MS = 30_000;
 const SA_CACHE_TTL_MS = 30_000;
+const CONTRACT_CACHE_TTL_MS = 30_000;
 
 const boostByAliasCache =
     getLRUCache<Awaited<ReturnType<typeof getBoostForListingByTemplateAlias>>>(200);
@@ -40,6 +42,8 @@ const listingSaCache =
     getLRUCache<Awaited<ReturnType<typeof getPrimarySigningAuthorityForListing>>>(200);
 const integrationSaCache =
     getLRUCache<Awaited<ReturnType<typeof getPrimarySigningAuthorityForIntegration>>>(200);
+const consentContractByScopeCache =
+    getLRUCache<Awaited<ReturnType<typeof getConsentContractForListingByScopeHash>>>(200);
 
 export const getBoostForListingCached = async (
     listingId: string,
@@ -54,6 +58,33 @@ export const getBoostForListingCached = async (
     return value;
 };
 
+export const invalidateBoostForListingCache = (
+    listingId: string,
+    templateAlias: string,
+    domain: string
+) => {
+    boostByAliasCache.invalidate(`${listingId}|${templateAlias}|${domain}`);
+};
+
+export const getConsentContractForListingByScopeHashCached = async (
+    listingId: string,
+    scopeHash: string
+) => {
+    const key = `${listingId}|${scopeHash}`;
+    const hit = consentContractByScopeCache.get(key);
+    if (hit !== undefined) return hit;
+    const value = await getConsentContractForListingByScopeHash(listingId, scopeHash);
+    consentContractByScopeCache.add(key, value, CONTRACT_CACHE_TTL_MS);
+    return value;
+};
+
+export const invalidateConsentContractForListingByScopeHashCache = (
+    listingId: string,
+    scopeHash: string
+) => {
+    consentContractByScopeCache.invalidate(`${listingId}|${scopeHash}`);
+};
+
 export const readAppStoreListingByIdCached = async (listingId: string) => {
     const hit = listingByIdCache.get(listingId);
     if (hit !== undefined) return hit;
@@ -87,6 +118,10 @@ export const getPrimarySigningAuthorityForListingCached = async (listing: AppSto
     return value;
 };
 
+export const invalidateListingSigningAuthorityCache = (listingId: string) => {
+    listingSaCache.invalidate(listingId);
+};
+
 export const getPrimarySigningAuthorityForIntegrationCached = async (integrationId: string) => {
     const hit = integrationSaCache.get(integrationId);
     if (hit !== undefined) return hit;

package/src/config/applyDockerStageConfig.ts

@@ -0,0 +1,6 @@
+import { applyBrainServiceStageConfig } from './stageConfig';
+
+// Side-effect import: runs before @environment is evaluated so Docker/local processes
+// pick up checked-in per-stage config. Keyed on CONFIG_STAGE (Lambda uses LAMBDA_STAGE);
+// explicit non-empty env values from the developer's .env still win.
+applyBrainServiceStageConfig(process.env.CONFIG_STAGE);

package/src/config/environment.test.ts

@@ -83,18 +83,23 @@ describe('credential refresh configuration', () => {
         }
     );
 
-    it.each(['serverless.yml', 'serverless-local.yml'])(
-        'passes all refresh settings into functions in %s',
-        manifestName => {
-            const manifestPath = fileURLToPath(new URL(`../../${manifestName}`, import.meta.url));
-            const manifest = parse(readFileSync(manifestPath, 'utf8'));
-
-            expect(manifest.provider.environment).toMatchObject({
-                CREDENTIAL_REFRESH_ENABLED: '${env:CREDENTIAL_REFRESH_ENABLED, "false"}',
-                CREDENTIAL_REFRESH_DIGEST_SECRET: '${env:CREDENTIAL_REFRESH_DIGEST_SECRET, ""}',
-                CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS:
-                    '${env:CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS, "24"}',
-            });
+    it('resolves the deployed function environment through the shared provider file', () => {
+        const manifestPath = fileURLToPath(new URL('../../serverless.yml', import.meta.url));
+        const manifest = parse(readFileSync(manifestPath, 'utf8'));
+
+        expect(manifest.provider.environment).toBe(
+            '${file(./serverless.function-env.cjs):provider}'
+        );
+    });
+
+    it.each(['config.dev.json', 'config.production.json'])(
+        'delivers non-secret refresh settings through checked-in stage config in %s',
+        stageFile => {
+            const configPath = fileURLToPath(new URL(`../../config/${stageFile}`, import.meta.url));
+            const config = JSON.parse(readFileSync(configPath, 'utf8'));
+
+            expect(config.CREDENTIAL_REFRESH_ENABLED).toBeDefined();
+            expect(config.CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS).toBeDefined();
         }
     );
 });

package/src/config/environment.ts

@@ -27,6 +27,7 @@ export const brainServiceEnvironmentShape = {
     CLIENT_APP_DOMAIN_NAME: optionalEnvironmentString,
     CLIENT_APP_PORT: optionalEnvironmentPort,
     LOGIN_PROVIDER_DID: optionalEnvironmentString,
+    SIGNING_AUTHORITY_ENDPOINT: optionalEnvironmentUrl,
     APP_STORE_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_ADMIN_PROFILE_IDS: optionalEnvironmentString,
     SKILL_FRAMEWORK_SEED_OWNER_PROFILE_ID: optionalEnvironmentString,

package/src/config/serverlessFunctionEnv.test.ts

@@ -0,0 +1,105 @@
+import { createRequire } from 'node:module';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    provider: (input?: {
+        options?: Record<string, unknown>;
+        env?: NodeJS.ProcessEnv;
+    }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+const INFRA_KEYS = {
+    LAMBDA_STAGE: 'dev',
+    PORT: '3000',
+    REDIS_HOST: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'] },
+    REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
+    NOTIFICATIONS_QUEUE_URL: '${construct:notifications-queue.queueUrl}',
+    INBOX_QUEUE_URL: '${construct:inbox-queue.queueUrl}',
+};
+
+beforeEach(() => {
+    vi.stubEnv('RUNTIME_SECRETS_ID', '');
+    vi.stubEnv('GIT_SHA', '');
+    vi.stubEnv('SEED', 'seed');
+    vi.stubEnv('NEO4J_PASSWORD', 'neo4j-password');
+    vi.stubEnv('SHARE_LINK_REQUEST_HASH_SECRET', 'hash-secret');
+    vi.stubEnv('SENTRY_AUTH_TOKEN', 'build-token');
+    vi.stubEnv('TRUSTED_ISSUERS_WHITELIST', 'did:web:issuer');
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('brain-service serverless provider environment', () => {
+    it('always emits Redis and queue infrastructure as unresolved references', () => {
+        expect(functions.provider({ options: { stage: 'dev' } })).toMatchObject(INFRA_KEYS);
+    });
+
+    it('derives LAMBDA_STAGE and PORT from the CLI options, never a stage passthrough', () => {
+        const result = functions.provider({ options: { stage: 'production', httpPort: 4000 } });
+        expect(result.LAMBDA_STAGE).toBe('production');
+        expect(result.PORT).toBe('4000');
+    });
+
+    it('defaults LAMBDA_STAGE and PORT when no CLI options are supplied', () => {
+        const result = functions.provider();
+        expect(result.LAMBDA_STAGE).toBe('dev');
+        expect(result.PORT).toBe('3000');
+    });
+
+    it('emits GIT_SHA only when it is set to a non-empty value', () => {
+        expect(functions.provider()).not.toHaveProperty('GIT_SHA');
+        vi.stubEnv('GIT_SHA', 'deadbeef');
+        expect(functions.provider()).toMatchObject({ GIT_SHA: 'deadbeef' });
+    });
+
+    it('omits every fallback credential and the pointer stays set in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'brain-service/dev/runtime-secrets');
+        const result = functions.provider({ options: { stage: 'dev' } });
+        expect(result).toMatchObject({
+            ...INFRA_KEYS,
+            RUNTIME_SECRETS_ID: 'brain-service/dev/runtime-secrets',
+        });
+        expect(result).not.toHaveProperty('SEED');
+        expect(result).not.toHaveProperty('NEO4J_PASSWORD');
+        expect(result).not.toHaveProperty('SHARE_LINK_REQUEST_HASH_SECRET');
+    });
+
+    it('retains only the approved fallback credentials when no bundle is configured', () => {
+        const result = functions.provider();
+        expect(result.SEED).toBe('seed');
+        expect(result.NEO4J_PASSWORD).toBe('neo4j-password');
+        expect(result.SHARE_LINK_REQUEST_HASH_SECRET).toBe('hash-secret');
+        expect(result.RUNTIME_SECRETS_ID).toBeUndefined();
+    });
+
+    it('never forwards Sentry build credentials or non-secret allowlists as fallbacks', () => {
+        const result = functions.provider();
+        expect(result).not.toHaveProperty('SENTRY_AUTH_TOKEN');
+        expect(result).not.toHaveProperty('SENTRY_ORG');
+        expect(result).not.toHaveProperty('SENTRY_PROJECT');
+        expect(result).not.toHaveProperty('TRUSTED_ISSUERS_WHITELIST');
+        expect(result).not.toHaveProperty('TRUSTED_BRAIN_SERVICES');
+        expect(result).not.toHaveProperty('BRAIN_SERVICE_REGISTRY_URL');
+        expect(result).not.toHaveProperty('DCC_KNOWN_REGISTRIES_URL');
+    });
+
+    it('resolves the provider through Serverless v3, preserving nested references in both modes', async () => {
+        const source = require('serverless/lib/configuration/variables/sources/file');
+        for (const bundle of ['', 'bundle']) {
+            vi.stubEnv('RUNTIME_SECRETS_ID', bundle);
+            const result = await source.resolve({
+                serviceDir: new URL('../../', import.meta.url).pathname,
+                params: [new URL('../../serverless.function-env.cjs', import.meta.url).pathname],
+                address: 'provider',
+                options: { stage: 'dev' },
+                resolveConfigurationProperty: vi.fn(),
+                resolveVariable: vi.fn(),
+            });
+            expect(result.value).toEqual(functions.provider({ options: { stage: 'dev' } }));
+            expect(result.value.NOTIFICATIONS_QUEUE_URL).toBe(
+                '${construct:notifications-queue.queueUrl}'
+            );
+            expect(result.value.INBOX_QUEUE_URL).toBe('${construct:inbox-queue.queueUrl}');
+        }
+    });
+});

package/src/config/stageConfig.test.ts

@@ -0,0 +1,25 @@
+import { afterEach, expect, it, vi } from 'vitest';
+
+vi.mock('dotenv/config', () => {
+    vi.stubEnv('SENTRY_ENV', 'self-hosted');
+    return {};
+});
+
+afterEach(() => vi.unstubAllEnvs());
+
+it('loads local env before applying statically imported stage defaults', async () => {
+    const { applyBrainServiceStageConfig, stages } = await import('./stageConfig');
+    for (const key of Object.keys(stages.dev)) {
+        if (key !== 'SENTRY_ENV') vi.stubEnv(key, '');
+    }
+    applyBrainServiceStageConfig('dev');
+    expect(process.env.SENTRY_ENV).toBe('self-hosted');
+    expect(process.env.DOMAIN_NAME).toBe(stages.dev.DOMAIN_NAME);
+});
+
+it('does not select a deployed stage for an unknown local stage', async () => {
+    const { applyBrainServiceStageConfig } = await import('./stageConfig');
+    vi.stubEnv('DOMAIN_NAME', '');
+    applyBrainServiceStageConfig('unregistered-self-hosted-stage');
+    expect(process.env.DOMAIN_NAME).toBe('');
+});

package/src/config/stageConfig.ts

@@ -0,0 +1,24 @@
+import 'dotenv/config';
+import { applyStageConfig } from '@learncard/service-config';
+
+import baseConfig from '../../config/config.json';
+import devConfig from '../../config/config.dev.json';
+import productionConfig from '../../config/config.production.json';
+import scoutsDevConfig from '../../config/config.scouts.dev.json';
+import scoutsProductionConfig from '../../config/config.scouts.production.json';
+
+export const base: Record<string, string> = baseConfig;
+
+export const stages = {
+    dev: devConfig,
+    production: productionConfig,
+    // ScoutPass deploys the same services and stage names; CONFIG_TENANT=scouts selects these.
+    'scouts.dev': scoutsDevConfig,
+    'scouts.production': scoutsProductionConfig,
+} satisfies Record<string, Record<string, string>>;
+
+// Must run before any module that reads configuration on import (e.g. @environment):
+// merges base + the selected stage into process.env; explicit non-empty env still wins.
+export const applyBrainServiceStageConfig = (stage: string | undefined): void => {
+    applyStageConfig({ base, stages, stage });
+};

package/src/docker-entry.ts

@@ -1,3 +1,6 @@
+import './config/applyDockerStageConfig';
+
+import { dispatchContractEvents } from '@helpers/contract-events.helpers';
 import { configureInboxBatchBodyLimit } from '@helpers/inbox-batch-http.helpers';
 import { environment } from '@environment';
 import Fastify from 'fastify';
@@ -41,8 +44,27 @@ const server = Fastify({ routerOptions: { maxParamLength: 5000 } });
  * graph/remote/signing dependency is initialized at all.
  */
 let shareLinkMaintenanceScheduler: ShareLinkMaintenanceScheduler | null = null;
+let contractEventTimer: ReturnType<typeof setTimeout> | null = null;
+let contractEventPass: Promise<unknown> | null = null;
+let contractEventsStopped = false;
+
+const runContractEventPass = (): void => {
+    if (contractEventsStopped) return;
+    contractEventPass = dispatchContractEvents()
+        .catch(() => {
+            console.warn('contract_events: recovery_pending');
+        })
+        .finally(() => {
+            contractEventPass = null;
+            if (!contractEventsStopped)
+                contractEventTimer = setTimeout(runContractEventPass, 60_000);
+        });
+};
 
 server.addHook('onClose', async () => {
+    contractEventsStopped = true;
+    if (contractEventTimer) clearTimeout(contractEventTimer);
+    await contractEventPass;
     await shareLinkMaintenanceScheduler?.stop();
 });
 // Register before either OpenAPI or tRPC registers its wildcard route. The hook raises the
@@ -167,6 +189,8 @@ server.register(credentialRefreshFastifyPlugin);
             console.error('Skill embedding backfill failed', error);
         }
 
+        contractEventTimer = setTimeout(runContractEventPass, 60_000);
+
         // Explicit startup after readiness. Disabled/invalid config stays inert.
         const maintenanceRuntime = createShareLinkMaintenanceRuntime();