@venturekit/infra 0.0.48 → 0.0.51

package/README.md

@@ -294,6 +294,40 @@ Changing `natType` on an existing deployment causes CloudFormation to
 replace the NAT resource (brief data-plane outage during deploy). The
 VPC itself is not replaced and all other resources stay put.
 
+## OpenTelemetry tracing (`lambda.otel`)
+
+Set `lambda.otel` in an environment config to trace every route, queue,
+cron and function Lambda with the AWS Lambda Layer for OpenTelemetry:
+
+```typescript
+// config/prod.ts
+export const prod = {
+  preset: 'medium',
+  lambda: {
+    otel: {
+      enabled: true,
+      // serviceName: 'cms-api',        // OTEL_SERVICE_NAME, default `<project>-<stage>`
+      // applicationSignals: true,      // CloudWatch Application Signals metrics too
+      // layerArn: 'arn:aws:lambda:…',  // pin a layer version
+    },
+  },
+};
+```
+
+The stack adds AWS's `AWSOpenTelemetryDistroJs` layer for its region (it
+counts toward the 5-layer limit), sets `AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument`,
+`OTEL_SERVICE_NAME` and `OTEL_AWS_APPLICATION_SIGNALS_ENABLED`, and turns
+on X-Ray active tracing. HTTP, AWS SDK and `pg` calls are traced
+automatically. Spans an app opens with the registered tracer go to X-Ray
+too: `otelTracer()` from `@venturekit-pro/ai` gives one, and passing it to
+the LLM gateway, the agent loop or the harness traces model calls, agents,
+tools and graph nodes. With `applicationSignals: true` the execution roles
+get `CloudWatchLambdaApplicationSignalsExecutionRolePolicy`; Application
+Signals must be enabled once in the account (CloudWatch console). The
+built-in layer versions are those AWS published in October 2026. Pin a
+newer one with `layerArn`. A region with no published layer needs
+`layerArn`.
+
 ## API
 
 ### `defineVenture(definition)`

package/dist/cdk/app-stack.d.ts

@@ -87,6 +87,12 @@ export interface AppStackImports {
      * functions.
      */
     vpc?: ec2.IVpc;
+    /**
+     * The VPC's INTERNAL CLIENTS security group (network tier): every Lambda
+     * joins it, which is what admits it to the VPC's internal service ports
+     * (`expose: 'vpc'`) — its own venture's and, in a shared VPC, the others'.
+     */
+    internalClientsSecurityGroupId?: string;
     /**
      * HttpApi imported from the edge stack via
      * `HttpApi.fromHttpApiAttributes({ httpApiId, apiEndpoint })`.
@@ -218,7 +224,12 @@ export interface AppStackImports {
         host: string;
         port: string;
         name: string;
+        /** The secret functions connect with — the APP login when provisioned. */
         secretArn?: string;
+        /** The SYSTEM login's secret — only the functions `systemFunctions` selects read it. */
+        systemSecretArn?: string;
+        /** `databases[].logins.system.functions` patterns. */
+        systemFunctions?: string[];
     }>;
     /**
      * Per-database connection params (RDS SG id + numeric port) used
@@ -362,10 +373,26 @@ export declare class VentureAppStack extends cdk.Stack {
      * single-role layout, where the shared role holds the admin grants.
      */
     readonly authAdminRole?: iam.Role;
+    /**
+     * Execution roles of the functions that connect as the SYSTEM database
+     * login (`databases[].logins.system.functions`): the only roles that may
+     * read its secret. Kept apart from the shared role so no app-login
+     * function — whatever runs in it — can fetch the system credential.
+     */
+    readonly dbSystemRole?: iam.Role;
+    readonly authAdminDbSystemRole?: iam.Role;
+    /** `logins.system.functions` of the primary database. */
+    private readonly systemLoginPatterns;
+    /** The primary database's two secrets, when the two logins are provisioned. */
+    private readonly dbLoginSecrets?;
     /** `adminRoutes` patterns collected across every auth intent. */
     private readonly adminRoutePatterns;
+    /** `auth[].adminRoutes: 'all'` — the explicit legacy layout (admin grants on the shared role). */
+    private readonly legacyAdminGrants;
     /** Shared SG when a VPC is imported; undefined for VPC-less projects. */
     readonly lambdaSecurityGroup?: ec2.SecurityGroup;
+    /** The VPC's internal clients group (see `AppStackImports.internalClientsSecurityGroupId`). */
+    readonly internalClientsSecurityGroup?: ec2.ISecurityGroup;
     /** Internal HMAC signing secret for Lambda-to-Lambda `invoke()`. */
     readonly internalHmacSecret: secretsmanager.Secret;
     /**
@@ -410,8 +437,10 @@ export declare class VentureAppStack extends cdk.Stack {
     private readonly stage;
     /** Ids of the imported RDS databases — logical `DBInstanceIdentifier` alarm dimensions. */
     private readonly rdsDatabaseIds;
-    /** `envConfig.lambda.layers`, attached to every route / queue / cron / function Lambda. */
+    /** `envConfig.lambda.layers` (+ the OpenTelemetry layer), attached to every route / queue / cron / function Lambda. */
     private readonly lambdaLayers;
+    /** X-Ray active tracing: `lambda.tracingEnabled`, or forced on by `lambda.otel`. */
+    private readonly tracingActive;
     /**
      * Resolved custom-sender KMS key ARN per declaring auth intent —
      * `imports.customSenderKmsKeyArnsByAuthId` merged with the
@@ -488,23 +517,47 @@ export declare class VentureAppStack extends cdk.Stack {
      * cross-stack pattern works the same as in-stack.
      */
     private createRouteFunction;
+    /** Every Lambda's groups: its own, and the VPC's internal clients group. */
+    private get lambdaSecurityGroups();
     /**
      * Every execution role in this stack: the shared role, plus the
      * auth-admin role when one exists. Baseline grants (secrets, S3,
      * SES, rate-limit table, …) are applied to all of them.
      */
     private get executionRoles();
+    /** The roles whose functions connect as the system database login. */
+    private get systemLoginRoles();
+    /**
+     * The role for a function: Cognito admin or not (`auth[].adminRoutes`),
+     * system database login or not (`databases[].logins.system.functions`).
+     */
+    private roleFor;
+    /** The database env a function running as `role` gets on top of the base env. */
+    private loginEnvFor;
     /**
-     * Roles that receive the Cognito admin grants: only the auth-admin
-     * role when `adminRoutes` are declared, otherwise the shared role
-     * (historical layout).
+     * Roles that receive the Cognito admin grants: the shared role under
+     * the explicit legacy layout (`adminRoutes: 'all'`), the auth-admin role
+     * when routes are listed, and none otherwise.
      */
     private get cognitoAdminRoles();
     /** Apply one grant to every execution role. */
     private grantEachRole;
+    /**
+     * Caches: the data stack's cache security group admits THIS stack's
+     * Lambda security group only, and every Lambda gets the endpoint and
+     * its AUTH token's secret (`VENTURE_CACHE_<ID>_HOST` / `_PORT` /
+     * `_AUTH_SECRET_ARN`; `cacheConnection(id)` in `@venturekit/runtime`
+     * turns them into TLS + AUTH connection options).
+     */
+    private wireCaches;
+    /**
+     * Internal routes (`internal` intent): the pair secrets this venture keeps
+     * for its callers, and the rights to call the ventures it calls.
+     */
+    private wireInternalRoutes;
     /** The role a route Lambda runs as — auth-admin when its API path matches `adminRoutes`. */
     private roleForRoute;
-    /** The role a standalone / queue / schedule Lambda runs as — auth-admin when `fn:<id>` matches. */
+    /** The role a standalone / queue / schedule Lambda runs as (`fn:<id>`). */
     private roleForFunction;
     /**
      * Build a Lambda function with the standard app-stack properties

package/dist/cdk/app-stack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-stack.d.ts","sourceRoot":"","sources":["../../src/cdk/app-stack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAKH,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AAQjD,OAAO,KAAK,YAAY,MAAM,8BAA8B,CAAC;AAM7D,OAAO,KAAK,cAAc,MAAM,gCAAgC,CAAC;AAEjE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAoB1B,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,iCAAiC,CAAC;AA6CzC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC;IAEf;;;;OAIG;IACH,GAAG,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3C;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3C,sDAAsD;IACtD,2BAA2B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElE;;;;;;;;;;;;;;OAcG;IACH,8BAA8B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErD,4EAA4E;IAC5E,sBAAsB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7C,mEAAmE;IACnE,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvC,wDAAwD;IACxD,yBAAyB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5C,uDAAuD;IACvD,+BAA+B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtD,6EAA6E;IAC7E,2BAA2B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElD;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;;;OAIG;IACH,iCAAiC,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExD;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAElD,+CAA+C;IAC/C,uBAAuB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,GAAG,CACzB,MAAM,EACN;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CACjE,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAAuB,CAAC,EAAE,GAAG,CAC3B,MAAM,EACN;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAC1C,CAAC;IAEF;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,oBAAqB,SAAQ,GAAG,CAAC,UAAU;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,SAAS,CAAC;IAErB,4EAA4E;IAC5E,cAAc,EAAE,aAAa,CAAC;IAE9B,yEAAyE;IACzE,OAAO,EAAE,eAAe,CAAC;IAEzB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,SAAQ,GAAG,CAAC,KAAK;IAC5C;;;;;OAKG;IACH,SAAgB,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC;IAErC;;;;;;;OAOG;IACH,SAAgB,aAAa,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC;IAEzC,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAoB;IAEvD,yEAAyE;IACzE,SAAgB,mBAAmB,CAAC,EAAE,GAAG,CAAC,aAAa,CAAC;IAExD,oEAAoE;IACpE,SAAgB,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAAC;IAE1D;;;;;;OAMG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpD,mEAAmE;IACnE,SAAgB,GAAG,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC;IAE5C,kCAAkC;IAClC,SAAgB,GAAG,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC;IAE/B;;;;;;OAMG;IACH,SAAgB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAEvE,oDAAoD;IACpD,SAAgB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAEvE,sDAAsD;IACtD,SAAgB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAE1E,wEAAwE;IACxE,SAAgB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAE1E,2DAA2D;IAC3D,SAAgB,uBAAuB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAElF,+DAA+D;IAC/D,SAAgB,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAa;IAE9E;;;;;OAKG;IACH,SAAgB,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsB;IAErD,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IAEtD;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IACtE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAEhD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAGjC;IAEJ;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAK;IAEnD;;;OAGG;IACH,OAAO,CAAC,uBAAuB;gBAanB,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB;IA8zBrE;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAyG3B;;;;OAIG;IACH,OAAO,KAAK,cAAc,GAEzB;IAED;;;;OAIG;IACH,OAAO,KAAK,iBAAiB,GAE5B;IAED,+CAA+C;IAC/C,OAAO,CAAC,aAAa;IAIrB,4FAA4F;IAC5F,OAAO,CAAC,YAAY;IAOpB,mGAAmG;IACnG,OAAO,CAAC,eAAe;IAOvB;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;IAiDnB;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAkD3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qBAAqB;IAuD7B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,wBAAwB;IA0BhC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,wBAAwB;IAqChC;;;;;;;;;OASG;IACH,OAAO,CAAC,eAAe;IA8DvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,OAAO,CAAC,gBAAgB;IA2DxB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAiC9B;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IAW/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,mBAAmB;IA+P3B;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,uBAAuB;CAsKhC"}
+{"version":3,"file":"app-stack.d.ts","sourceRoot":"","sources":["../../src/cdk/app-stack.ts"],"names":[],"mappings":"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"}

package/dist/cdk/app-stack.js

@@ -87,10 +87,13 @@ import * as cloudwatchActions from 'aws-cdk-lib/aws-cloudwatch-actions';
 import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
 import * as logs from 'aws-cdk-lib/aws-logs';
 import { DATA_SAFETY_CONFIG, isExternalAuthIntent, } from '@venturekit/core';
-import { collectAdminRoutePatterns, matchesAdminRoute } from './shared/admin-routes.js';
-import { readSsmString } from './shared/cross-stack-refs.js';
+import { collectAdminRoutePatterns, matchesAdminRoute, usesLegacyAdminGrants } from './shared/admin-routes.js';
+import { isInternalRoute, matchesFunctionPattern } from '@venturekit/core';
+import { createInternalCallerSecrets, internalCallStatements } from './shared/internal-routes.js';
+import { readSsmString, writeSsm } from './shared/cross-stack-refs.js';
+import { APPLICATION_SIGNALS_POLICY, defaultOtelLayerArn, otelEnvironment } from './shared/otel-layer.js';
 import { grantCustomSenderInvoke, resolveCustomSender } from './shared/custom-sender.js';
-import { networkKeys, edgeKeys, identityKeys, dataKeys } from './shared/ssm-keys.js';
+import { networkKeys, edgeKeys, identityKeys, dataKeys, internalKeys } from './shared/ssm-keys.js';
 import { bundleHandlerCodeWithEsbuild, inlineStubLambdaCode, toLambdaArchitecture, toLambdaRuntime, toLogRetention, clampLambdaFunctionName, uniqueLogGroupName, discoverFunctionFiles, } from './shared/lambda-helpers.js';
 import { discoverRouteFiles, } from './shared/route-discovery.js';
 import { discoverWsRoutes } from './shared/ws-discovery.js';
@@ -168,10 +171,26 @@ export class VentureAppStack extends cdk.Stack {
      * single-role layout, where the shared role holds the admin grants.
      */
     authAdminRole;
+    /**
+     * Execution roles of the functions that connect as the SYSTEM database
+     * login (`databases[].logins.system.functions`): the only roles that may
+     * read its secret. Kept apart from the shared role so no app-login
+     * function — whatever runs in it — can fetch the system credential.
+     */
+    dbSystemRole;
+    authAdminDbSystemRole;
+    /** `logins.system.functions` of the primary database. */
+    systemLoginPatterns;
+    /** The primary database's two secrets, when the two logins are provisioned. */
+    dbLoginSecrets;
     /** `adminRoutes` patterns collected across every auth intent. */
     adminRoutePatterns;
+    /** `auth[].adminRoutes: 'all'` — the explicit legacy layout (admin grants on the shared role). */
+    legacyAdminGrants;
     /** Shared SG when a VPC is imported; undefined for VPC-less projects. */
     lambdaSecurityGroup;
+    /** The VPC's internal clients group (see `AppStackImports.internalClientsSecurityGroupId`). */
+    internalClientsSecurityGroup;
     /** Internal HMAC signing secret for Lambda-to-Lambda `invoke()`. */
     internalHmacSecret;
     /**
@@ -216,8 +235,10 @@ export class VentureAppStack extends cdk.Stack {
     stage;
     /** Ids of the imported RDS databases — logical `DBInstanceIdentifier` alarm dimensions. */
     rdsDatabaseIds;
-    /** `envConfig.lambda.layers`, attached to every route / queue / cron / function Lambda. */
+    /** `envConfig.lambda.layers` (+ the OpenTelemetry layer), attached to every route / queue / cron / function Lambda. */
     lambdaLayers;
+    /** X-Ray active tracing: `lambda.tracingEnabled`, or forced on by `lambda.otel`. */
+    tracingActive;
     /**
      * Resolved custom-sender KMS key ARN per declaring auth intent —
      * `imports.customSenderKmsKeyArnsByAuthId` merged with the
@@ -301,11 +322,24 @@ export class VentureAppStack extends cdk.Stack {
         this.stage = stage;
         this.rdsDatabaseIds = new Set(imports.databaseEndpointsById?.keys() ?? []);
         this.envConfig = envConfig;
-        const layerArns = envConfig.lambda.layers ?? [];
+        const otel = envConfig.lambda.otel?.enabled ? envConfig.lambda.otel : undefined;
+        let otelLayerArn;
+        if (otel) {
+            const region = cdk.Stack.of(this).region;
+            otelLayerArn =
+                otel.layerArn ?? (cdk.Token.isUnresolved(region) ? undefined : defaultOtelLayerArn(region));
+            if (!otelLayerArn) {
+                throw new Error(cdk.Token.isUnresolved(region)
+                    ? `[venturekit] lambda.otel: the stack has no concrete region to pick the AWS OpenTelemetry layer — set lambda.otel.layerArn.`
+                    : `[venturekit] lambda.otel: AWS publishes no OpenTelemetry layer for '${region}' — set lambda.otel.layerArn.`);
+            }
+        }
+        this.tracingActive = envConfig.lambda.tracingEnabled || Boolean(otel);
+        const layerArns = [...(envConfig.lambda.layers ?? []), ...(otelLayerArn ? [otelLayerArn] : [])];
         if (layerArns.length > 5) {
-            throw new Error(`[venturekit] lambda.layers has ${layerArns.length} ARNs; Lambda allows at most 5.`);
+            throw new Error(`[venturekit] lambda.layers has ${layerArns.length} ARNs${otel ? ' (with the OpenTelemetry layer)' : ''}; Lambda allows at most 5.`);
         }
-        this.lambdaLayers = layerArns.map((arn, i) => lambda.LayerVersion.fromLayerVersionArn(this, `lambda-layer-${i}`, arn));
+        this.lambdaLayers = layerArns.map((arn, i) => lambda.LayerVersion.fromLayerVersionArn(this, arn === otelLayerArn && i === layerArns.length - 1 ? 'lambda-layer-otel' : `lambda-layer-${i}`, arn));
         this.skipBundling = props.skipBundling ?? false;
         this.projectDir = props.projectDir;
         // Stamp once per synth so every route Lambda in this deploy reports
@@ -344,7 +378,13 @@ export class VentureAppStack extends cdk.Stack {
         // CFN's 500-resource limit on large projects is the reason the
         // per-function layout was never adopted.
         this.adminRoutePatterns = collectAdminRoutePatterns(infrastructure.auth ?? []);
-        if (this.adminRoutePatterns.length > 0) {
+        this.legacyAdminGrants = usesLegacyAdminGrants(infrastructure.auth ?? []);
+        if (this.legacyAdminGrants) {
+            cdk.Annotations.of(this).addWarning(`[venturekit] auth[].adminRoutes is 'all': every Lambda in ${projectName}/${stage} shares one role ` +
+                `that can create users, set passwords and edit attributes on the user pool. List the routes that ` +
+                `call @venturekit/auth/server admin flows (e.g. adminRoutes: ['/auth/**']) to confine those grants.`);
+        }
+        else if (this.adminRoutePatterns.length > 0) {
             this.authAdminRole = new iam.Role(this, 'AuthAdminRole', {
                 assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
                 description: `Execution role for ${projectName}-${stage} Lambdas allowed to call Cognito admin APIs (auth[].adminRoutes)`,
@@ -354,10 +394,33 @@ export class VentureAppStack extends cdk.Stack {
             });
         }
         else if ((infrastructure.auth ?? []).length > 0) {
-            cdk.Annotations.of(this).addWarning(`[venturekit] auth intents declare no 'adminRoutes': every Lambda in ${projectName}/${stage} ` +
-                `shares one role that can create users, set passwords and edit attributes on the user pool. ` +
-                `List the routes that call @venturekit/auth/server admin flows (e.g. adminRoutes: ['/auth/**']) ` +
-                `to confine those grants to them.`);
+            cdk.Annotations.of(this).addInfo(`[venturekit] auth intents declare no 'adminRoutes': no Lambda in ${projectName}/${stage} can call ` +
+                `Cognito admin APIs. Routes that run @venturekit/auth/server admin flows (sign-up, federated ` +
+                `sign-in, password reset, …) must be listed in auth[].adminRoutes.`);
+        }
+        // ─── System-login execution roles (databases[].logins) ──────
+        const primaryDb = imports.databaseEndpointsById?.values().next().value;
+        this.systemLoginPatterns = (primaryDb?.systemFunctions ?? []).map((p) => p.trim()).filter(Boolean);
+        if (primaryDb?.secretArn && primaryDb.systemSecretArn) {
+            this.dbLoginSecrets = { app: primaryDb.secretArn, system: primaryDb.systemSecretArn };
+        }
+        if (this.dbLoginSecrets && this.systemLoginPatterns.length > 0) {
+            const executionRole = (id, description) => new iam.Role(this, id, {
+                assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
+                description,
+                managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole')],
+            });
+            this.dbSystemRole = executionRole('DbSystemRole', `Execution role for ${projectName}-${stage} Lambdas on the system database login (databases[].logins.system)`);
+            if (this.authAdminRole) {
+                this.authAdminDbSystemRole = executionRole('AuthAdminDbSystemRole', `Execution role for ${projectName}-${stage} Lambdas with Cognito admin grants on the system database login`);
+            }
+        }
+        if (otel?.applicationSignals) {
+            // CloudWatch Application Signals: the layer publishes service
+            // metrics and traces under this role.
+            for (const role of this.executionRoles) {
+                role.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName(APPLICATION_SIGNALS_POLICY));
+            }
         }
         if (this.vpc) {
             // VPC-attached Lambdas need ENI-creation rights on cold start.
@@ -366,6 +429,9 @@ export class VentureAppStack extends cdk.Stack {
             for (const role of this.executionRoles) {
                 role.addManagedPolicy(iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole'));
             }
+            if (imports.internalClientsSecurityGroupId) {
+                this.internalClientsSecurityGroup = ec2.SecurityGroup.fromSecurityGroupId(this, 'InternalClientsSg', imports.internalClientsSecurityGroupId);
+            }
             this.lambdaSecurityGroup = new ec2.SecurityGroup(this, 'LambdaSg', {
                 vpc: this.vpc,
                 description: `Shared SG for ${projectName}-${stage} Lambdas`,
@@ -476,7 +542,18 @@ export class VentureAppStack extends cdk.Stack {
             // `--enable-source-maps` makes thrown errors point to the
             // .ts source instead of bundled .js. Free win in CloudWatch.
             NODE_OPTIONS: '--enable-source-maps',
+            // `lambda.otel`: the wrapper starts the layer's OpenTelemetry SDK
+            // (it appends its own `--require` to NODE_OPTIONS at startup).
+            ...(otel
+                ? otelEnvironment({
+                    serviceName: otel.serviceName ?? `${projectName}-${stage}`,
+                    applicationSignals: otel.applicationSignals === true,
+                })
+                : {}),
         };
+        // Caches need the env map (endpoint + AUTH secret) and the Lambda SG.
+        this.wireCaches(infrastructure.caches ?? [], projectName, stage);
+        this.wireInternalRoutes(infrastructure.internal, projectName, stage);
         // ─── Cross-tier env injection (cheap, static keys only) ────
         // Per-intent keys go through helpers in sub-steps 9b/c/d. The
         // ones below are stack-wide singletons — primary DB, primary
@@ -503,6 +580,11 @@ export class VentureAppStack extends cdk.Stack {
             if (primaryIntent?.tenantRole) {
                 this.baseEnvVars['DB_TENANT_ROLE'] = primaryIntent.tenantRole;
             }
+            // Two logins: every function is on the APP login unless its role is a
+            // system-login one (`loginEnvFor` switches the secret and DB_LOGIN).
+            if (primary.systemSecretArn) {
+                this.baseEnvVars['DB_LOGIN'] = 'app';
+            }
         }
         if (imports.storageBucketNamesById && imports.storageBucketNamesById.size > 0) {
             const [, primaryBucket] = imports.storageBucketNamesById.entries().next().value;
@@ -567,6 +649,13 @@ export class VentureAppStack extends cdk.Stack {
                     this.baseEnvVars[`${prefix}_USER_POOL_ID`] = poolId;
                 if (clientId)
                     this.baseEnvVars[`${prefix}_APP_CLIENT_ID`] = clientId;
+                // The primary client's refresh-token rotation, so `refreshSession`
+                // takes the rotating flow (`@venturekit/auth` `loadAuthServerConfig`).
+                if (intent.clients?.[0]?.refreshTokenRotation?.enabled) {
+                    this.baseEnvVars[`${prefix}_REFRESH_TOKEN_ROTATION`] = 'true';
+                    if (intent === (infrastructure.auth ?? [])[0])
+                        this.baseEnvVars['COGNITO_REFRESH_TOKEN_ROTATION'] = 'true';
+                }
             }
             this.baseEnvVars[`${prefix}_REGION`] = cdk.Stack.of(this).region;
         }
@@ -723,14 +812,14 @@ export class VentureAppStack extends cdk.Stack {
             this.baseEnvVars['COGNITO_CUSTOM_SENDER_KMS_KEY_ARN'] ??= keyArn;
         }
         // ─── Billing provider secret ARNs (billing intents) ─────
-        // `@venturekit/billing`'s resolveZazuConfig() reads the API key,
+        // `@venturekit/billing`'s resolveManzaConfig() reads the API key,
         // account id, and webhook secret from the Secrets Manager entry named
-        // by `ZAZU_SECRET_ARN`. Inject it here — the matching read grant is
+        // by `MANZA_SECRET_ARN`. Inject it here — the matching read grant is
         // attached in applyImportedGrants — so a project that declares a
         // billing intent needs no wiring of its own.
         //
         // The env var name is derived from the provider, not the intent id,
-        // because the runtime resolver is provider-scoped (one Zazu account
+        // because the runtime resolver is provider-scoped (one Manza account
         // per stage). The first declared intent for a given provider wins,
         // mirroring COGNITO_FEDERATED_<PROVIDER>_SECRET_ARN.
         if (imports.billingSecretArnsById) {
@@ -738,7 +827,9 @@ export class VentureAppStack extends cdk.Stack {
                 const intent = infrastructure.billing?.find((b) => b.id === id);
                 if (!intent)
                     continue;
-                const key = `${intent.provider.toUpperCase()}_SECRET_ARN`;
+                // `'zazu'` is the deprecated name of `'manza'`.
+                const provider = intent.provider === 'zazu' ? 'manza' : intent.provider;
+                const key = `${provider.toUpperCase()}_SECRET_ARN`;
                 if (!(key in this.baseEnvVars)) {
                     this.baseEnvVars[key] = arn;
                 }
@@ -785,7 +876,11 @@ export class VentureAppStack extends cdk.Stack {
                     stage,
                     envConfig,
                     lambdaRole: this.lambdaRole,
+                    roleFor: (routeKey) => this.roleFor({ wsRoute: routeKey }),
+                    envFor: (routeKey) => this.loginEnvFor(this.roleFor({ wsRoute: routeKey })),
+                    extraRoles: this.executionRoles.filter((r) => r !== this.lambdaRole),
                     lambdaSecurityGroup: this.lambdaSecurityGroup,
+                    extraSecurityGroups: this.internalClientsSecurityGroup ? [this.internalClientsSecurityGroup] : [],
                     vpc: this.vpc,
                     baseEnvVars: this.baseEnvVars,
                     skipBundling: this.skipBundling,
@@ -1089,11 +1184,10 @@ export class VentureAppStack extends cdk.Stack {
             environment: {
                 ...this.baseEnvVars,
                 ...lambdaConfig.environmentVariables,
+                ...this.loginEnvFor(this.roleForRoute(route.apiPath)),
             },
             logGroup,
-            tracing: lambdaConfig.tracingEnabled
-                ? lambda.Tracing.ACTIVE
-                : lambda.Tracing.DISABLED,
+            tracing: this.tracingActive ? lambda.Tracing.ACTIVE : lambda.Tracing.DISABLED,
             reservedConcurrentExecutions: lambdaConfig.reservedConcurrency,
             role: this.roleForRoute(route.apiPath),
             // Attach to the VPC iff one exists. Route Lambdas without a VPC
@@ -1104,7 +1198,7 @@ export class VentureAppStack extends cdk.Stack {
                 ? {
                     vpc: this.vpc,
                     vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
-                    securityGroups: [this.lambdaSecurityGroup],
+                    securityGroups: this.lambdaSecurityGroups,
                 }
                 : {}),
         });
@@ -1115,6 +1209,10 @@ export class VentureAppStack extends cdk.Stack {
         cdk.Tags.of(fn).add('deployedAt', this.deployedAt);
         cdk.Tags.of(logGroup).add('deployedAt', this.deployedAt);
         this.routeLambdas.set(route.slug, fn);
+        // An internal route is on no public API: other ventures invoke its
+        // function directly (`internalFetch`), so a public request is a 404.
+        if (isInternalRoute(route.apiPath))
+            return;
         // Add the HttpRoute on the imported API. `HttpRouteKey.with`
         // builds the canonical `${METHOD} ${path}` string AWS uses
         // internally; passing path + method separately keeps us honest
@@ -1125,40 +1223,110 @@ export class VentureAppStack extends cdk.Stack {
             integration: new apigatewayv2Integrations.HttpLambdaIntegration(`${resourceId}-integration`, fn),
         });
     }
+    /** Every Lambda's groups: its own, and the VPC's internal clients group. */
+    get lambdaSecurityGroups() {
+        return [this.lambdaSecurityGroup, ...(this.internalClientsSecurityGroup ? [this.internalClientsSecurityGroup] : [])];
+    }
     /**
      * Every execution role in this stack: the shared role, plus the
      * auth-admin role when one exists. Baseline grants (secrets, S3,
      * SES, rate-limit table, …) are applied to all of them.
      */
     get executionRoles() {
-        return this.authAdminRole ? [this.lambdaRole, this.authAdminRole] : [this.lambdaRole];
+        return [this.lambdaRole, this.authAdminRole, this.dbSystemRole, this.authAdminDbSystemRole].filter((r) => r !== undefined);
+    }
+    /** The roles whose functions connect as the system database login. */
+    get systemLoginRoles() {
+        return [this.dbSystemRole, this.authAdminDbSystemRole].filter((r) => r !== undefined);
     }
     /**
-     * Roles that receive the Cognito admin grants: only the auth-admin
-     * role when `adminRoutes` are declared, otherwise the shared role
-     * (historical layout).
+     * The role for a function: Cognito admin or not (`auth[].adminRoutes`),
+     * system database login or not (`databases[].logins.system.functions`).
+     */
+    roleFor(subject) {
+        const admin = Boolean(this.authAdminRole) && matchesAdminRoute(this.adminRoutePatterns, subject);
+        const system = Boolean(this.dbSystemRole) && matchesFunctionPattern(this.systemLoginPatterns, subject);
+        if (admin && system)
+            return this.authAdminDbSystemRole;
+        if (admin)
+            return this.authAdminRole;
+        if (system)
+            return this.dbSystemRole;
+        return this.lambdaRole;
+    }
+    /** The database env a function running as `role` gets on top of the base env. */
+    loginEnvFor(role) {
+        if (!this.dbLoginSecrets || !role || !this.systemLoginRoles.includes(role))
+            return {};
+        return { DB_SECRET_ARN: this.dbLoginSecrets.system, DB_LOGIN: 'system' };
+    }
+    /**
+     * Roles that receive the Cognito admin grants: the shared role under
+     * the explicit legacy layout (`adminRoutes: 'all'`), the auth-admin role
+     * when routes are listed, and none otherwise.
      */
     get cognitoAdminRoles() {
-        return this.authAdminRole ? [this.authAdminRole] : [this.lambdaRole];
+        if (this.legacyAdminGrants)
+            return [this.lambdaRole, ...(this.dbSystemRole ? [this.dbSystemRole] : [])];
+        return [this.authAdminRole, this.authAdminDbSystemRole].filter((r) => r !== undefined);
     }
     /** Apply one grant to every execution role. */
     grantEachRole(grant) {
         for (const role of this.executionRoles)
             grant(role);
     }
+    /**
+     * Caches: the data stack's cache security group admits THIS stack's
+     * Lambda security group only, and every Lambda gets the endpoint and
+     * its AUTH token's secret (`VENTURE_CACHE_<ID>_HOST` / `_PORT` /
+     * `_AUTH_SECRET_ARN`; `cacheConnection(id)` in `@venturekit/runtime`
+     * turns them into TLS + AUTH connection options).
+     */
+    wireCaches(caches, projectName, stage) {
+        if (!this.lambdaSecurityGroup)
+            return;
+        for (const cache of caches) {
+            const cacheSg = ec2.SecurityGroup.fromSecurityGroupId(this, `imported-cache-sg-${cache.id}`, readSsmString(this, dataKeys.cacheSecurityGroupId(projectName, stage, cache.id)), { mutable: true });
+            cacheSg.connections.allowFrom(this.lambdaSecurityGroup, ec2.Port.tcp(6379), `Allow ${projectName}-${stage} Lambdas to connect to cache ${cache.id}`);
+            const prefix = `VENTURE_CACHE_${upperSnake(cache.id)}`;
+            const secretArn = readSsmString(this, dataKeys.cacheAuthSecretArn(projectName, stage, cache.id));
+            this.baseEnvVars[`${prefix}_HOST`] = readSsmString(this, dataKeys.cacheEndpoint(projectName, stage, cache.id));
+            this.baseEnvVars[`${prefix}_PORT`] = readSsmString(this, dataKeys.cachePort(projectName, stage, cache.id));
+            this.baseEnvVars[`${prefix}_AUTH_SECRET_ARN`] = secretArn;
+            const secret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-cache-auth-${cache.id}`, secretArn);
+            this.grantEachRole((role) => secret.grantRead(role));
+        }
+    }
+    /**
+     * Internal routes (`internal` intent): the pair secrets this venture keeps
+     * for its callers, and the rights to call the ventures it calls.
+     */
+    wireInternalRoutes(internal, projectName, stage) {
+        const secrets = createInternalCallerSecrets(this, projectName, stage, internal, this.isStrictRetain);
+        if (secrets.size > 0) {
+            for (const [caller, secret] of secrets) {
+                this.grantEachRole((role) => secret.grantRead(role));
+                // What the caller's `vk deploy` checks before deploying (`verifyInternalCalls`).
+                writeSsm(this, internalKeys.callerSecretArn(projectName, stage, caller), secret.secretArn, {
+                    description: `Pair secret ${caller} → ${projectName} internal routes`,
+                });
+            }
+            this.baseEnvVars.VENTURE_INTERNAL_CALLER_SECRET_ARNS = JSON.stringify(Object.fromEntries([...secrets].map(([caller, secret]) => [caller, secret.secretArn])));
+            // Who may call — what a caller's `vk deploy` checks it is part of.
+            writeSsm(this, internalKeys.callers(projectName, stage), [...secrets.keys()].join(','), {
+                description: `Ventures allowed to call ${projectName} internal routes`,
+            });
+        }
+        const statements = internalCallStatements(this, projectName, stage, internal);
+        this.grantEachRole((role) => statements.forEach((s) => role.addToPolicy(s)));
+    }
     /** The role a route Lambda runs as — auth-admin when its API path matches `adminRoutes`. */
     roleForRoute(apiPath) {
-        if (this.authAdminRole && matchesAdminRoute(this.adminRoutePatterns, { apiPath })) {
-            return this.authAdminRole;
-        }
-        return this.lambdaRole;
+        return this.roleFor({ apiPath });
     }
-    /** The role a standalone / queue / schedule Lambda runs as — auth-admin when `fn:<id>` matches. */
+    /** The role a standalone / queue / schedule Lambda runs as (`fn:<id>`). */
     roleForFunction(id) {
-        if (this.authAdminRole && matchesAdminRoute(this.adminRoutePatterns, { functionId: id })) {
-            return this.authAdminRole;
-        }
-        return this.lambdaRole;
+        return this.roleFor({ functionId: id });
     }
     /**
      * Build a Lambda function with the standard app-stack properties
@@ -1190,14 +1358,8 @@ export class VentureAppStack extends cdk.Stack {
             memorySize: lambdaConfig.memoryMb,
             timeout: cdk.Duration.seconds(lambdaConfig.timeoutSec),
             description,
-            environment: {
-                ...this.baseEnvVars,
-                ...lambdaConfig.environmentVariables,
-            },
             logGroup,
-            tracing: lambdaConfig.tracingEnabled
-                ? lambda.Tracing.ACTIVE
-                : lambda.Tracing.DISABLED,
+            tracing: this.tracingActive ? lambda.Tracing.ACTIVE : lambda.Tracing.DISABLED,
             reservedConcurrentExecutions: lambdaConfig.reservedConcurrency,
             role: this.lambdaRole,
             ...(this.vpc && this.lambdaSecurityGroup
@@ -1208,6 +1370,11 @@ export class VentureAppStack extends cdk.Stack {
                 }
                 : {}),
             ...overrides,
+            // The database login follows the role (a system-login role reads the system secret).
+            environment: {
+                ...(overrides.environment ?? { ...this.baseEnvVars, ...lambdaConfig.environmentVariables }),
+                ...this.loginEnvFor(overrides.role),
+            },
         });
     }
     /**
@@ -1610,7 +1777,14 @@ export class VentureAppStack extends cdk.Stack {
                 if (!db.secretArn)
                     continue;
                 const importedSecret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-db-secret-${id}`, db.secretArn);
+                // The app login's secret to every role; the system login's to the
+                // system-login roles ONLY.
                 this.grantEachRole((role) => importedSecret.grantRead(role));
+                if (db.systemSecretArn && this.systemLoginRoles.length > 0) {
+                    const systemSecret = secretsmanager.Secret.fromSecretCompleteArn(this, `imported-db-system-secret-${id}`, db.systemSecretArn);
+                    for (const role of this.systemLoginRoles)
+                        systemSecret.grantRead(role);
+                }
             }
         }
         // ── Federated provider secrets ────────────────────────────
@@ -1679,8 +1853,9 @@ export class VentureAppStack extends cdk.Stack {
             }
         }
         // ── Cognito admin actions per user pool ──────────────────
-        // Attached to the auth-admin role only when `adminRoutes` are
-        // declared (see the constructor), otherwise to the shared role.
+        // Attached to the auth-admin role when `adminRoutes` lists routes,
+        // to the shared role under `adminRoutes: 'all'`, and to no role
+        // otherwise (see `cognitoAdminRoles`).
         if (imports.userPoolArnsByAuthId) {
             for (const [, poolArn] of imports.userPoolArnsByAuthId) {
                 // Scope to the Cognito admin actions `@venturekit/auth/server`