@learncard/network-brain-service 3.19.1 → 4.0.0

package/serverless.function-env.cjs

@@ -0,0 +1,50 @@
+const { functionEnvironment, pickNonEmpty } = require('@learncard/service-config/function-env.cjs');
+
+// User-approved brain-service deployment credentials. In bundle mode these are delivered
+// through the runtime-secrets bundle and omitted here; in fallback mode (no bundle) the
+// existing per-value GitHub environment secrets are retained. Only genuine credentials
+// belong in this list — non-secret allowlists, tuning flags and per-stage values are
+// delivered through checked-in stage config at cold start, never forwarded here.
+const PROVIDER_SECRETS = [
+    'SEED',
+    'NEO4J_URI',
+    'NEO4J_USERNAME',
+    'NEO4J_PASSWORD',
+    'POSTMARK_API_KEY',
+    'MESSAGEBIRD_AUTH_TOKEN',
+    'SENTRY_DSN',
+    'POSTHOG_API_KEY',
+    'SKILL_EMBEDDING_GOOGLE_API_KEY',
+    'SKILLS_PROVIDER_API_KEY',
+    'TWILIO_ACCOUNT_SID',
+    'TWILIO_AUTH_TOKEN',
+    'SMART_RESUME_CLIENT_ID',
+    'SMART_RESUME_ACCESS_KEY',
+    'SMART_RESUME_CONTRACT_URI',
+    'CREDENTIAL_REFRESH_DIGEST_SECRET',
+    'SHARE_LINK_REQUEST_HASH_SECRET',
+    'APP_STORE_ADMIN_PROFILE_IDS',
+    'LOGIN_PROVIDER_DID',
+    'NOTIFICATIONS_SERVICE_WEBHOOK_URL',
+];
+
+// Serverless v3 supplies CLI options to file functions and recursively resolves the strings
+// it returns, so CloudFormation intrinsics (Fn::GetAtt) and construct references survive.
+// Every brain-service function shares the one generated execution role, so the bundle pointer
+// and the credential fallbacks sit together on the provider. Bundle mode emits only infra plus
+// the pointer; fallback mode retains the per-value GitHub secrets. Non-secret per-stage tuning
+// and allowlists are applied from checked-in stage config at cold start, never forwarded here.
+exports.provider = ({ options = {}, env = process.env } = {}) => ({
+    LAMBDA_STAGE: options.stage || 'dev',
+    // Non-secret product selector for the shared stage files (config.<tenant>.<stage>.json).
+    CONFIG_TENANT: env.CONFIG_TENANT || 'learncard',
+    PORT: String(options.httpPort || '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}',
+    // The deploy commit, emitted only when set so an empty string never counts toward the
+    // 4KB per-function environment limit.
+    ...pickNonEmpty(['GIT_SHA'], env),
+    ...functionEnvironment({ always: ['RUNTIME_SECRETS_ID'], fallback: PROVIDER_SECRETS, env }),
+});

package/serverless.local.yml

@@ -64,7 +64,6 @@ provider:
             'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Address]
         REDIS_PORT:
             'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Port]
-        APP_BRAND: ${env:APP_BRAND, 'scouts'}
     tracing:
         apiGateway: true
         lambda: true

package/serverless.yml

@@ -138,80 +138,20 @@ provider:
     timeout: 29
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
-    environment:
-        PORT: ${env:PORT, 3000}
-        INBOX_DELETE_EXPIRED_RECORDS: ${env:INBOX_DELETE_EXPIRED_RECORDS, "false"}
-        LAMBDA_STAGE: ${opt:stage, "dev"}
-        INBOX_BATCH_ITEMS_PER_HOUR: ${env:INBOX_BATCH_ITEMS_PER_HOUR, '10000'}
-        SEED: ${env:SEED}
-        DOMAIN_NAME: ${env:DOMAIN_NAME}
-        CLIENT_APP_DOMAIN_NAME: ${env:CLIENT_APP_DOMAIN_NAME}
-        NOTIFICATIONS_SERVICE_WEBHOOK_URL: ${env:NOTIFICATIONS_SERVICE_WEBHOOK_URL}
-        NEO4J_URI: ${env:NEO4J_URI}
-        NEO4J_USERNAME: ${env:NEO4J_USERNAME}
-        NEO4J_PASSWORD: ${env:NEO4J_PASSWORD}
-        POSTMARK_API_KEY: ${env:POSTMARK_API_KEY}
-        POSTMARK_FROM_EMAIL: ${env:POSTMARK_FROM_EMAIL}
-        MESSAGEBIRD_AUTH_TOKEN: ${env:MESSAGEBIRD_AUTH_TOKEN}
-        MESSAGEBIRD_ORIGINATOR: ${env:MESSAGEBIRD_ORIGINATOR}
-        TRUSTED_ISSUERS_WHITELIST: ${env:TRUSTED_ISSUERS_WHITELIST, ""}
-        TRUSTED_BRAIN_SERVICES: ${env:TRUSTED_BRAIN_SERVICES, ""}
-        BRAIN_SERVICE_REGISTRY_URL: ${env:BRAIN_SERVICE_REGISTRY_URL, ""}
-        DCC_KNOWN_REGISTRIES_URL: ${env:DCC_KNOWN_REGISTRIES_URL, ""}
-        SENTRY_DSN: ${env:SENTRY_DSN}
-        SENTRY_ENV: ${env:SENTRY_ENV}
-        SENTRY_AUTH_TOKEN: ${env:SENTRY_AUTH_TOKEN}
-        SENTRY_ORG: ${env:SENTRY_ORG}
-        SENTRY_PROJECT: ${env:SENTRY_PROJECT}
-        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}
-        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"}
-        SKILL_EMBEDDING_BACKFILL_ON_STARTUP: ${env:SKILL_EMBEDDING_BACKFILL_ON_STARTUP, "false"}
-        SKILL_EMBEDDING_BACKFILL_LOCK_TTL_SECONDS: ${env:SKILL_EMBEDDING_BACKFILL_LOCK_TTL_SECONDS, "900"}
-        SKILL_EMBEDDING_BACKFILL_PAGE_SIZE: ${env:SKILL_EMBEDDING_BACKFILL_PAGE_SIZE, "100"}
-        SKILL_EMBEDDING_BACKFILL_BATCH_SIZE: ${env:SKILL_EMBEDDING_BACKFILL_BATCH_SIZE, "50"}
-        SMART_RESUME_CLIENT_ID: ${env:SMART_RESUME_CLIENT_ID, ""}
-        SMART_RESUME_ACCESS_KEY: ${env:SMART_RESUME_ACCESS_KEY, ""}
-        SMART_RESUME_CONTRACT_URI: ${env:SMART_RESUME_CONTRACT_URI, ""}
-        LOGIN_PROVIDER_DID: ${env:LOGIN_PROVIDER_DID, ""}
-        OIDC_TRUSTED_ISSUERS: ${env:OIDC_TRUSTED_ISSUERS, ""}
-        OIDC_EXPECTED_AUDIENCE: ${env:OIDC_EXPECTED_AUDIENCE, ""}
-        APP_STORE_ADMIN_PROFILE_IDS: ${env:APP_STORE_ADMIN_PROFILE_IDS, ""}
-        APP_BRAND: ${env:APP_BRAND, 'scouts'}
-        # LC-1644 perf bench (admin-only). Optional — if unset, the bench still runs
-        # but emits no PostHog events. POSTHOG_HOST falls back to the helper's default
-        # (https://us.i.posthog.com).
-        POSTHOG_API_KEY: ${env:POSTHOG_API_KEY, ""}
-        POSTHOG_HOST: ${env:POSTHOG_HOST, ""}
-        GIT_SHA: ${env:GIT_SHA, ""}
-        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"}
-        # Stable HMAC key for passcode-bearing share-link request fingerprints.
-        SHARE_LINK_REQUEST_HASH_SECRET: ${env:SHARE_LINK_REQUEST_HASH_SECRET, ""}
-        # LC-2187 share-link service wiring and automatic maintenance. Every value is
-        # bounded and re-validated fail-closed at runtime. Never read from the
-        # scheduled event payload.
-        SHARE_LINK_MAINTENANCE_NAMESPACE: ${env:SHARE_LINK_MAINTENANCE_NAMESPACE, ""}
-        SHARE_LINK_MAINTENANCE_ORIGIN: ${env:SHARE_LINK_MAINTENANCE_ORIGIN, ""}
-        SHARE_LINK_MAINTENANCE_AUDIENCE: ${env:SHARE_LINK_MAINTENANCE_AUDIENCE, ""}
-        SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK: ${env:SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK, "false"}
-        SHARE_LINK_MAINTENANCE_CLAIMANT: ${env:SHARE_LINK_MAINTENANCE_CLAIMANT, "brain-share-link-maintenance"}
-        SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT: ${env:SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT, "25"}
-        SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT: ${env:SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT, "25"}
-        SHARE_LINK_MAINTENANCE_LEASE_MS: ${env:SHARE_LINK_MAINTENANCE_LEASE_MS, "120000"}
-        SHARE_LINK_MAINTENANCE_CLAIM_MS: ${env:SHARE_LINK_MAINTENANCE_CLAIM_MS, "300000"}
-        SHARE_LINK_MAINTENANCE_BUDGET_MS: ${env:SHARE_LINK_MAINTENANCE_BUDGET_MS, "60000"}
-        SHARE_LINK_MAINTENANCE_INTERVAL_MS: ${env:SHARE_LINK_MAINTENANCE_INTERVAL_MS, "300000"}
-        SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS: ${env:SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS, "10000"}
-        SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS: ${env:SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS, "5000"}
-        SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS: ${env:SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS, "15000"}
+    # 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.
+    iam:
+        role:
+            statements:
+                - Effect: Allow
+                  Action: secretsmanager:GetSecretValue
+                  Resource:
+                      Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:brain-service/${sls:stage}/runtime-secrets-*
+    # 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
+    # config at cold start, never forwarded here. LAMBDA_STAGE comes from the CLI stage option.
+    environment: ${file(./serverless.function-env.cjs):provider}
     tracing:
         apiGateway: true
         lambda: true
@@ -263,6 +203,19 @@ functions:
                   rate: rate(1 day)
                   enabled: true
 
+    # Retry durable consent notification intents once per minute.
+    contractEvents:
+        handler: contractEventsLambda.contractEventsHandler
+        timeout: 60
+        reservedConcurrency: 1
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule: rate(1 minute)
+
     # LC-2187 share-link recovery + cleanup. Dedicated entrypoint (no lambda.ts
     # import-time work). Runs automatically with valid service configuration;
     # absent wiring remains inert and partial wiring fails closed. The cadence

package/shareLinkMaintenanceLambda.ts

@@ -1,49 +1,18 @@
-import type { Context } from 'aws-lambda';
+import { bootstrapLambda } from '@learncard/service-config';
 
-import {
-    createShareLinkMaintenanceRuntime,
-    type ShareLinkMaintenanceRuntime,
-} from './src/helpers/share-link-maintenance';
+import { base, stages } from './src/config/stageConfig';
 
-/**
- * Dedicated LC-2187 share-link maintenance Lambda entrypoint.
- *
- * It deliberately does NOT import `lambda.ts`, so no unrelated embedding
- * backfill, tRPC router, Sentry input capture or inbox handler runs at import
- * time. The only side effect is resolving the service and maintenance
- * configuration; when it is absent or malformed the runtime is inert and the
- * handler performs no graph, remote or signing work.
- *
- * The scheduled event payload is ignored entirely: it can never override the
- * namespace, origin, audience or any other configuration, and it is never
- * logged.
- */
+type ShareLinkMaintenanceApp = typeof import('./shareLinkMaintenanceLambdaApp');
 
-let runtime: ShareLinkMaintenanceRuntime | null = null;
-
-const getRuntime = (): ShareLinkMaintenanceRuntime => {
-    if (runtime === null) {
-        runtime = createShareLinkMaintenanceRuntime({
-            rawEnvironment: process.env as Record<string, unknown>,
-        });
-    }
-
-    return runtime;
-};
+const getApplication = bootstrapLambda<ShareLinkMaintenanceApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./shareLinkMaintenanceLambdaApp'),
+});
 
 export const shareLinkMaintenanceHandler = async (
-    _event: unknown,
-    context?: Pick<Context, 'getRemainingTimeInMillis'>
-): Promise<{ status: string }> => {
-    const hasRemainingTime = typeof context?.getRemainingTimeInMillis === 'function';
-
-    const summary = await getRuntime().runOnce({
-        // Preserve the LIVE Lambda remaining-time source: the runtime samples it
-        // once, before dependency initialization, and anchors the invocation
-        // budget to that instant.
-        remainingTimeMs: hasRemainingTime ? () => context!.getRemainingTimeInMillis() : undefined,
-    });
-
-    // The runtime already emitted one aggregate-only allowlisted event.
-    return { status: summary.status };
-};
+    ...args: Parameters<ShareLinkMaintenanceApp['shareLinkMaintenanceHandler']>
+) => (await getApplication()).shareLinkMaintenanceHandler(...args);

package/shareLinkMaintenanceLambdaApp.ts

@@ -0,0 +1,50 @@
+import type { Context } from 'aws-lambda';
+
+import {
+    createShareLinkMaintenanceRuntime,
+    type ShareLinkMaintenanceRuntime,
+} from './src/helpers/share-link-maintenance';
+
+/**
+ * Dedicated LC-2187 share-link maintenance application module.
+ *
+ * It is imported lazily by the thin bootstrap entrypoint, after checked-in
+ * stage config has been applied, so no unrelated embedding backfill, tRPC
+ * router, Sentry input capture or inbox handler runs at import time. The only
+ * side effect is resolving the service and maintenance configuration; when it
+ * is absent or malformed the runtime is inert and the handler performs no
+ * graph, remote or signing work.
+ *
+ * The scheduled event payload is ignored entirely: it can never override the
+ * namespace, origin, audience or any other configuration, and it is never
+ * logged.
+ */
+
+let runtime: ShareLinkMaintenanceRuntime | null = null;
+
+const getRuntime = (): ShareLinkMaintenanceRuntime => {
+    if (runtime === null) {
+        runtime = createShareLinkMaintenanceRuntime({
+            rawEnvironment: process.env as Record<string, unknown>,
+        });
+    }
+
+    return runtime;
+};
+
+export const shareLinkMaintenanceHandler = async (
+    _event: unknown,
+    context?: Pick<Context, 'getRemainingTimeInMillis'>
+): Promise<{ status: string }> => {
+    const hasRemainingTime = typeof context?.getRemainingTimeInMillis === 'function';
+
+    const summary = await getRuntime().runOnce({
+        // Preserve the LIVE Lambda remaining-time source: the runtime samples it
+        // once, before dependency initialization, and anchors the invocation
+        // budget to that instant.
+        remainingTimeMs: hasRemainingTime ? () => context!.getRemainingTimeInMillis() : undefined,
+    });
+
+    // The runtime already emitted one aggregate-only allowlisted event.
+    return { status: summary.status };
+};

package/src/accesslayer/app-manifest-version/create.ts

@@ -0,0 +1,57 @@
+import { BindParam, QueryBuilder } from 'neogma';
+import { v4 as uuid } from 'uuid';
+
+import { Integration, AppManifestVersion } from '@models';
+import type { AppManifest } from '@learncard/types';
+
+import type { AppManifestVersionType } from 'types/app-manifest';
+
+import { readAppManifestVersionById } from './read';
+
+export const createAppManifestVersion = async ({
+    integrationId,
+    version,
+    manifestHash,
+    manifest,
+    status = 'draft',
+}: {
+    integrationId: string;
+    version: number;
+    manifestHash: string;
+    manifest: AppManifest;
+    status?: 'draft' | 'active' | 'superseded';
+}): Promise<AppManifestVersionType> => {
+    const id = uuid();
+    const createdAt = new Date().toISOString();
+
+    await new QueryBuilder(
+        new BindParam({
+            integrationId,
+            params: {
+                id,
+                version,
+                manifestHash,
+                manifestJson: JSON.stringify(manifest),
+                status,
+                createdAt,
+            },
+        })
+    )
+        .match({ model: Integration, identifier: 'integration', where: { id: integrationId } })
+        .create({ model: AppManifestVersion, identifier: 'manifestVersion' })
+        .set('manifestVersion += $params')
+        .create(
+            `(integration)-[:${
+                Integration.getRelationshipByAlias('hasManifestVersion').name
+            }]->(manifestVersion)`
+        )
+        .run();
+
+    const created = await readAppManifestVersionById(id);
+
+    if (!created) {
+        throw new Error('Failed to create app manifest version');
+    }
+
+    return created;
+};

package/src/accesslayer/app-manifest-version/read.ts

@@ -0,0 +1,129 @@
+import { neogma } from '@instance';
+
+import { AppManifestVersionValidator } from '@learncard/types';
+
+import type { AppManifestVersionType } from 'types/app-manifest';
+
+const parseManifestVersionRecord = (
+    properties: Record<string, unknown>
+): AppManifestVersionType => {
+    const manifestJson = properties.manifestJson;
+    const rawVersion = properties.version as { toNumber?: () => number } | number;
+
+    if (typeof manifestJson !== 'string') {
+        throw new Error('AppManifestVersion.manifestJson is missing');
+    }
+
+    return AppManifestVersionValidator.parse({
+        id: properties.id,
+        version: typeof rawVersion === 'number' ? rawVersion : rawVersion?.toNumber?.(),
+        manifestHash: properties.manifestHash,
+        manifest: JSON.parse(manifestJson),
+        status: properties.status,
+        createdAt: properties.createdAt,
+        activatedAt: properties.activatedAt,
+    });
+};
+
+export const readAppManifestVersionById = async (
+    id: string
+): Promise<AppManifestVersionType | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (manifestVersion:AppManifestVersion {id: $id})
+         RETURN manifestVersion
+         LIMIT 1`,
+        { id }
+    );
+
+    const properties = result.records[0]?.get('manifestVersion')?.properties;
+
+    if (!properties) return null;
+
+    return parseManifestVersionRecord(properties as Record<string, unknown>);
+};
+
+export const getManifestVersionForIntegration = async (
+    integrationId: string,
+    version: number
+): Promise<AppManifestVersionType | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (:Integration {id: $integrationId})-[:HAS_MANIFEST_VERSION]->(manifestVersion:AppManifestVersion {version: $version})
+         RETURN manifestVersion
+         LIMIT 1`,
+        { integrationId, version }
+    );
+
+    const properties = result.records[0]?.get('manifestVersion')?.properties;
+
+    if (!properties) return null;
+
+    return parseManifestVersionRecord(properties as Record<string, unknown>);
+};
+
+export const getLatestManifestVersionForIntegration = async (
+    integrationId: string
+): Promise<AppManifestVersionType | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (:Integration {id: $integrationId})-[:HAS_MANIFEST_VERSION]->(manifestVersion:AppManifestVersion)
+         RETURN manifestVersion
+         ORDER BY manifestVersion.version DESC
+         LIMIT 1`,
+        { integrationId }
+    );
+
+    const properties = result.records[0]?.get('manifestVersion')?.properties;
+
+    if (!properties) return null;
+
+    return parseManifestVersionRecord(properties as Record<string, unknown>);
+};
+
+export const getActiveManifestVersionForIntegration = async (
+    integrationId: string
+): Promise<AppManifestVersionType | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (:Integration {id: $integrationId})-[:HAS_MANIFEST_VERSION]->(manifestVersion:AppManifestVersion {status: 'active'})
+         RETURN manifestVersion
+         ORDER BY manifestVersion.activatedAt DESC, manifestVersion.version DESC
+         LIMIT 1`,
+        { integrationId }
+    );
+
+    const properties = result.records[0]?.get('manifestVersion')?.properties;
+
+    if (!properties) return null;
+
+    return parseManifestVersionRecord(properties as Record<string, unknown>);
+};
+
+export const getManifestVersionsForIntegration = async (
+    integrationId: string,
+    { limit, cursor }: { limit: number; cursor?: string }
+): Promise<AppManifestVersionType[]> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (:Integration {id: $integrationId})-[:HAS_MANIFEST_VERSION]->(manifestVersion:AppManifestVersion)
+         ${cursor ? 'WHERE manifestVersion.version < toInteger($cursor)' : ''}
+         RETURN manifestVersion
+         ORDER BY manifestVersion.version DESC
+         LIMIT toInteger($limit)`,
+        { integrationId, cursor: cursor ?? null, limit }
+    );
+
+    return result.records.map(record => {
+        const properties = record.get('manifestVersion')?.properties as Record<string, unknown>;
+        return parseManifestVersionRecord(properties);
+    });
+};
+
+export const getListingIdForManifestVersion = async (id: string): Promise<string | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (listing:AppStoreListing)-[:USES_MANIFEST_VERSION]->(:AppManifestVersion {id: $id})
+         RETURN listing.listing_id AS listingId
+         LIMIT 1`,
+        { id }
+    );
+
+    const listingId = result.records[0]?.get('listingId');
+
+    return typeof listingId === 'string' ? listingId : null;
+};

package/src/accesslayer/app-manifest-version/update.ts

@@ -0,0 +1,61 @@
+import { neogma } from '@instance';
+
+export const updateAppManifestVersion = async (
+    id: string,
+    updates: Partial<{
+        status: 'draft' | 'active' | 'superseded';
+        activatedAt: string | null;
+    }>
+): Promise<boolean> => {
+    const setClauses: string[] = [];
+    const params: Record<string, unknown> = { id };
+
+    if (typeof updates.status !== 'undefined') {
+        params.status = updates.status;
+        setClauses.push('manifestVersion.status = $status');
+    }
+    if (typeof updates.activatedAt !== 'undefined') {
+        params.activatedAt = updates.activatedAt;
+        setClauses.push('manifestVersion.activatedAt = $activatedAt');
+    }
+
+    if (setClauses.length === 0) return true;
+
+    const result = await neogma.queryRunner.run(
+        `MATCH (manifestVersion:AppManifestVersion {id: $id})
+         SET ${setClauses.join(', ')}`,
+        params
+    );
+
+    return result.summary.updateStatistics.containsUpdates();
+};
+
+export const markManifestVersionsSuperseded = async (
+    integrationId: string,
+    exceptId: string
+): Promise<boolean> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (:Integration {id: $integrationId})-[:HAS_MANIFEST_VERSION]->(manifestVersion:AppManifestVersion)
+         WHERE manifestVersion.id <> $exceptId AND manifestVersion.status = 'active'
+         SET manifestVersion.status = 'superseded'`,
+        { integrationId, exceptId }
+    );
+
+    return result.summary.updateStatistics.containsUpdates();
+};
+
+export const associateListingWithManifestVersion = async (
+    listingId: string,
+    manifestVersionId: string
+): Promise<boolean> => {
+    await neogma.queryRunner.run(
+        `MATCH (listing:AppStoreListing {listing_id: $listingId})
+         MATCH (manifestVersion:AppManifestVersion {id: $manifestVersionId})
+         OPTIONAL MATCH (listing)-[existing:USES_MANIFEST_VERSION]->(:AppManifestVersion)
+         DELETE existing
+         MERGE (listing)-[:USES_MANIFEST_VERSION]->(manifestVersion)`,
+        { listingId, manifestVersionId }
+    );
+
+    return true;
+};

package/src/accesslayer/app-store-listing/read.ts

@@ -244,16 +244,22 @@ export const getListedAppsWithSubmitter = async ({
     status,
     includeAllStatuses = false,
     excludeDemoted = true,
+    pendingUpdatesOnly = false,
 }: {
     limit: number;
     cursor?: string;
     status?: string;
     includeAllStatuses?: boolean;
     excludeDemoted?: boolean;
+    pendingUpdatesOnly?: boolean;
 }): Promise<ListingWithSubmitter[]> => {
     const whereClauses: string[] = [];
     const params: Record<string, any> = { limit: int(limit) };
 
+    if (pendingUpdatesOnly) {
+        whereClauses.push("listing.pending_update_status = 'PENDING_REVIEW'");
+    }
+
     if (status) {
         whereClauses.push('listing.app_listing_status = $status');
         params.status = status;

package/src/accesslayer/app-store-listing/relationships/create.ts

@@ -96,6 +96,26 @@ export const associateBoostWithListing = async (
     return true;
 };
 
+export const associateConsentContractWithListing = async (
+    listingId: string,
+    contractId: string,
+    scopeHash: string
+): Promise<boolean> => {
+    await AppStoreListing.relateTo({
+        alias: 'hasConsentContract',
+        where: {
+            source: { listing_id: listingId },
+            target: { id: contractId },
+        },
+        properties: {
+            scopeHash,
+            createdAt: new Date().toISOString(),
+        },
+    });
+
+    return true;
+};
+
 export const associateListingWithSigningAuthority = async (
     listingId: string,
     signingAuthorityEndpoint: string,

package/src/accesslayer/app-store-listing/relationships/read.ts

@@ -6,6 +6,8 @@ import { Boost, BoostInstance } from '@models';
 import { int } from 'neo4j-driver';
 import { getBoostUri } from '@helpers/boost.helpers';
 import { parseIntegration } from '@helpers/integrations.helpers';
+import { getContractById } from '@accesslayer/consentflowcontract/read';
+import type { DbContractType } from 'types/consentflowcontract';
 
 export const getIntegrationForListing = async (
     listingIdOrSlug: string
@@ -93,7 +95,9 @@ export const getBoostForListingByTemplateAlias = async (
 ): Promise<{ boost: BoostInstance; templateAlias: string; boostUri: string } | null> => {
     const result = await neogma.queryRunner.run(
         `MATCH (listing:AppStoreListing {listing_id: $listingId})-[r:HAS_BOOST {templateAlias: $templateAlias}]->(b:Boost)
-         RETURN b.id AS id, r.templateAlias AS templateAlias`,
+         RETURN b.id AS id, r.templateAlias AS templateAlias
+         ORDER BY r.createdAt DESC
+         LIMIT 1`,
         { listingId, templateAlias }
     );
 
@@ -146,6 +150,25 @@ export const hasTemplateAliasForListing = async (
     return result.records[0]?.get('exists') ?? false;
 };
 
+export const getConsentContractForListingByScopeHash = async (
+    listingId: string,
+    scopeHash: string
+): Promise<DbContractType | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (listing:AppStoreListing {listing_id: $listingId})
+               -[:HAS_CONSENT_CONTRACT {scopeHash: $scopeHash}]->(contract:ConsentFlowContract)
+         RETURN contract.id AS id
+         ORDER BY contract.createdAt ASC
+         LIMIT 1`,
+        { listingId, scopeHash }
+    );
+
+    const id = result.records[0]?.get('id');
+    if (typeof id !== 'string') return null;
+
+    return getContractById(id);
+};
+
 export const getCredentialsSentByListingToProfile = async (
     listingId: string,
     profileId: string,

package/src/accesslayer/app-store-listing/update.ts

@@ -1,6 +1,7 @@
 import { QueryBuilder, BindParam } from 'neogma';
 
 import { AppStoreListing } from '@models';
+import { neogma } from '@instance';
 import {
     FlatAppStoreListingType,
     AppStoreListingType,
@@ -50,6 +51,12 @@ export const updateAppStoreListing = async (
         updatesToPersist.submitted_at = updates.submitted_at;
     if (typeof updates.contact_email !== 'undefined')
         updatesToPersist.contact_email = updates.contact_email;
+    if (typeof updates.pending_update_json !== 'undefined')
+        updatesToPersist.pending_update_json = updates.pending_update_json;
+    if (typeof updates.pending_update_status !== 'undefined')
+        updatesToPersist.pending_update_status = updates.pending_update_status;
+    if (typeof updates.pending_update_submitted_at !== 'undefined')
+        updatesToPersist.pending_update_submitted_at = updates.pending_update_submitted_at;
 
     const params: Partial<FlatAppStoreListingType> = updatesToPersist;
 
@@ -67,3 +74,11 @@ export const updateAppStoreListing = async (
 
     return result.summary.updateStatistics.containsUpdates();
 };
+
+export const clearPendingListingUpdate = async (listingId: string): Promise<void> => {
+    await neogma.queryRunner.run(
+        `MATCH (listing:AppStoreListing {listing_id: $listingId})
+         REMOVE listing.pending_update_json, listing.pending_update_status, listing.pending_update_submitted_at`,
+        { listingId }
+    );
+};