@go-to-k/cdkd 0.130.0 → 0.132.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-CuHRHcyW.js";
-import { A as AssetPublisher, B as getLegacyStateBucketName, C as applyRoleArnIfSet, Ct as generateResourceNameWithFallback, D as LockManager, E as TemplateParser, F as getDockerCmd, G as resolveStateBucketWithDefaultAndSource, H as resolveCaptureObservedState, I as runDockerForeground, K as warnDeprecatedNoPrefixCliFlag, L as runDockerStreaming, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as formatDockerLoginError, R as Synthesizer, S as IntrinsicFunctionResolver, St as generateResourceName, T as DagBuilder, Tt as withStackName, U as resolveSkipPrefix, V as resolveApp, W as resolveStateBucketWithDefault, Y as resolveBucketRegion, Z as CdkdError, _ as normalizeAwsTagsToCfn, a as withRetry, at as ResourceUpdateNotSupportedError, b as CloudControlProvider, bt as PATTERN_B_NAME_PROPERTIES, c as cyan, ct as StackTerminationProtectionError, d as red, et as LocalInvokeBuildError, f as yellow, g as matchesCdkPath, gt as getLogger, h as CDK_PATH_TAG, i as withResourceDeadline, it as ResourceTimeoutError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, mt as withErrorHandling, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as PartialFailureError, o as IMPLICIT_DELETE_DEPENDENCIES, ot as RouteDiscoveryError, p as IAMRoleProvider, pt as normalizeAwsError, q as AssemblyReader, r as DeployEngine, rt as ProvisioningError, s as bold, st as StackHasActiveImportsError, t as DEFAULT_RESOURCE_TIMEOUT_MS, u as green, v as resolveExplicitPhysicalId, vt as runStackBuffered, w as DiffCalculator, wt as withSkipPrefix, x as assertRegionMatch, xt as PATTERN_B_RESOURCE_TYPES, y as ProviderRegistry, yt as getLiveRenderer, z as getDefaultStateBucketName } from "./deploy-engine-B-w4C_7O.js";
+import { _ as withSkipPrefix, a as runDockerStreaming, c as getLogger, d as getLiveRenderer, f as PATTERN_B_NAME_PROPERTIES, g as generateResourceNameWithFallback, h as generateResourceName, i as runDockerForeground, n as formatDockerLoginError, p as PATTERN_B_RESOURCE_TYPES, r as getDockerCmd, u as runStackBuffered, v as withStackName } from "./docker-cmd-EtWSTAje.js";
+import { $ as PartialFailureError, A as AssetPublisher, B as resolveStateBucketWithDefault, C as applyRoleArnIfSet, D as LockManager, E as TemplateParser, F as getDefaultStateBucketName, G as resolveBucketRegion, H as warnDeprecatedNoPrefixCliFlag, I as getLegacyStateBucketName, L as resolveApp, M as WorkGraph, N as buildDockerImage, O as S3StateBackend, P as Synthesizer, R as resolveCaptureObservedState, S as IntrinsicFunctionResolver, T as DagBuilder, U as AssemblyReader, V as resolveStateBucketWithDefaultAndSource, X as LocalInvokeBuildError, Z as LocalStartServiceError, _ as normalizeAwsTagsToCfn, a as withRetry, at as StackTerminationProtectionError, b as CloudControlProvider, c as cyan, d as red, dt as withErrorHandling, et as ProvisioningError, f as yellow, g as matchesCdkPath, h as CDK_PATH_TAG, i as withResourceDeadline, it as StackHasActiveImportsError, j as stringifyValue, k as shouldRetainResource, l as gray, m as collectInlinePolicyNamesManagedBySiblings, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as ResourceUpdateNotSupportedError, o as IMPLICIT_DELETE_DEPENDENCIES, p as IAMRoleProvider, q as CdkdError, r as DeployEngine, rt as RouteDiscoveryError, s as bold, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as ResourceTimeoutError, u as green, ut as normalizeAwsError, v as resolveExplicitPhysicalId, w as DiffCalculator, x as assertRegionMatch, y as ProviderRegistry, z as resolveSkipPrefix } from "./deploy-engine-Dn7oV5rA.js";
+import { a as setAwsClients, i as resetAwsClients, r as getAwsClients, t as AwsClients } from "./aws-clients-BF03Alpe.js";
 import { createHash, createHmac, createPublicKey, createVerify, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { CopyObjectCommand, CreateBucketCommand, DeleteBucketAnalyticsConfigurationCommand, DeleteBucketCommand, DeleteBucketCorsCommand, DeleteBucketIntelligentTieringConfigurationCommand, DeleteBucketInventoryConfigurationCommand, DeleteBucketLifecycleCommand, DeleteBucketMetricsConfigurationCommand, DeleteBucketPolicyCommand, DeleteBucketReplicationCommand, DeleteBucketTaggingCommand, DeleteBucketWebsiteCommand, DeleteObjectCommand, DeleteObjectsCommand, GetBucketAccelerateConfigurationCommand, GetBucketCorsCommand, GetBucketEncryptionCommand, GetBucketLifecycleConfigurationCommand, GetBucketLocationCommand, GetBucketLoggingCommand, GetBucketNotificationConfigurationCommand, GetBucketPolicyCommand, GetBucketReplicationCommand, GetBucketTaggingCommand, GetBucketVersioningCommand, GetBucketWebsiteCommand, GetObjectCommand, GetObjectLockConfigurationCommand, GetPublicAccessBlockCommand, HeadBucketCommand, ListBucketAnalyticsConfigurationsCommand, ListBucketIntelligentTieringConfigurationsCommand, ListBucketInventoryConfigurationsCommand, ListBucketMetricsConfigurationsCommand, ListBucketsCommand, ListDirectoryBucketsCommand, ListObjectVersionsCommand, ListObjectsV2Command, NoSuchBucket, PutBucketAccelerateConfigurationCommand, PutBucketAnalyticsConfigurationCommand, PutBucketCorsCommand, PutBucketEncryptionCommand, PutBucketIntelligentTieringConfigurationCommand, PutBucketInventoryConfigurationCommand, PutBucketLifecycleConfigurationCommand, PutBucketLoggingCommand, PutBucketMetricsConfigurationCommand, PutBucketNotificationConfigurationCommand, PutBucketOwnershipControlsCommand, PutBucketPolicyCommand, PutBucketReplicationCommand, PutBucketTaggingCommand, PutBucketVersioningCommand, PutBucketWebsiteCommand, PutObjectCommand, PutObjectLockConfigurationCommand, PutPublicAccessBlockCommand, S3Client, S3ServiceException } from "@aws-sdk/client-s3";
 import { AddRoleToInstanceProfileCommand, AddUserToGroupCommand, AttachGroupPolicyCommand, AttachUserPolicyCommand, CreateGroupCommand, CreateInstanceProfileCommand, CreateLoginProfileCommand, CreateUserCommand, DeleteAccessKeyCommand, DeleteGroupCommand, DeleteGroupPolicyCommand, DeleteInstanceProfileCommand, DeleteLoginProfileCommand, DeleteRolePolicyCommand, DeleteUserCommand, DeleteUserPermissionsBoundaryCommand, DeleteUserPolicyCommand, DetachGroupPolicyCommand, DetachUserPolicyCommand, GetGroupCommand, GetGroupPolicyCommand, GetInstanceProfileCommand, GetRolePolicyCommand, GetUserCommand, GetUserPolicyCommand, IAMClient, ListAccessKeysCommand, ListAttachedGroupPoliciesCommand, ListAttachedUserPoliciesCommand, ListGroupPoliciesCommand, ListGroupsForUserCommand, ListInstanceProfilesCommand, ListUserPoliciesCommand, ListUserTagsCommand, ListUsersCommand, NoSuchEntityException, PutGroupPolicyCommand, PutRolePolicyCommand, PutUserPermissionsBoundaryCommand, PutUserPolicyCommand, RemoveRoleFromInstanceProfileCommand, RemoveUserFromGroupCommand, TagUserCommand, UntagUserCommand, UpdateLoginProfileCommand } from "@aws-sdk/client-iam";
@@ -36541,14 +36542,14 @@ function parseTarget(target) {
 function resolveLambdaTarget(target, stacks) {
 	if (stacks.length === 0) throw new LocalInvokeResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseTarget(target);
-	const stack = pickStack$1(parsed, stacks);
+	const stack = pickStack$2(parsed, stacks);
 	const template = stack.template;
 	const resources = template.Resources ?? {};
 	let match;
 	if (parsed.isPath) {
 		const index = buildCdkPathIndex(template);
 		const lambdaMatches = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId }) => resources[logicalId]?.Type === "AWS::Lambda::Function");
-		if (lambdaMatches.length === 0) throw notFoundError$1(target, stack, resources);
+		if (lambdaMatches.length === 0) throw notFoundError$2(target, stack, resources);
 		if (lambdaMatches.length > 1) throw new LocalInvokeResolutionError(`Target '${target}' matches ${lambdaMatches.length} Lambda functions in ${stack.stackName}: ` + lambdaMatches.map((m) => m.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
 		const m = lambdaMatches[0];
 		match = {
@@ -36557,7 +36558,7 @@ function resolveLambdaTarget(target, stacks) {
 		};
 	} else {
 		const resource = resources[parsed.pathOrId];
-		if (!resource) throw notFoundError$1(target, stack, resources);
+		if (!resource) throw notFoundError$2(target, stack, resources);
 		match = {
 			logicalId: parsed.pathOrId,
 			resource
@@ -36575,7 +36576,7 @@ function resolveLambdaTarget(target, stacks) {
 * user may omit the stack prefix. Otherwise an explicit stack pattern is
 * required.
 */
-function pickStack$1(parsed, stacks) {
+function pickStack$2(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new LocalInvokeResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -36912,7 +36913,7 @@ function describeLayerEntry(entry) {
 * the resolved stack so the user can copy/paste a valid target. Mirrors
 * the format the issue spec calls out.
 */
-function notFoundError$1(target, stack, resources) {
+function notFoundError$2(target, stack, resources) {
 	const lambdas = [];
 	for (const [logicalId, resource] of Object.entries(resources)) {
 		if (resource.Type !== "AWS::Lambda::Function") continue;
@@ -37936,28 +37937,28 @@ function parseEcsTarget(target) {
 function resolveEcsTaskTarget(target, stacks, context) {
 	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
 	const parsed = parseEcsTarget(target);
-	const stack = pickStack(parsed, stacks);
+	const stack = pickStack$1(parsed, stacks);
 	const resources = stack.template.Resources ?? {};
 	let logicalId;
 	let resource;
 	if (parsed.isPath) {
 		const index = buildCdkPathIndex(stack.template);
 		const taskDefs = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::TaskDefinition");
-		if (taskDefs.length === 0) throw notFoundError(target, stack, resources);
+		if (taskDefs.length === 0) throw notFoundError$1(target, stack, resources);
 		if (taskDefs.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${taskDefs.length} task definitions in ${stack.stackName}: ` + taskDefs.map((t) => t.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
 		logicalId = taskDefs[0].logicalId;
 		resource = resources[logicalId];
 	} else {
 		resource = resources[parsed.pathOrId];
-		if (!resource) throw notFoundError(target, stack, resources);
+		if (!resource) throw notFoundError$1(target, stack, resources);
 		logicalId = parsed.pathOrId;
 	}
-	if (!logicalId || !resource) throw notFoundError(target, stack, resources);
+	if (!logicalId || !resource) throw notFoundError$1(target, stack, resources);
 	if (resource.Type === "AWS::Lambda::Function") throw new EcsTaskResolutionError(`Resource '${logicalId}' in ${stack.stackName} is a Lambda function, not an ECS task definition. Use \`cdkd local invoke\` for Lambda; \`cdkd local run-task\` is ECS only.`);
 	if (resource.Type !== "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${logicalId}' in ${stack.stackName} is ${resource.Type}, not an AWS::ECS::TaskDefinition.`);
 	return extractTaskDefinitionProperties(stack, logicalId, resource, context);
 }
-function pickStack(parsed, stacks) {
+function pickStack$1(parsed, stacks) {
 	if (parsed.stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		throw new EcsTaskResolutionError(`Multiple stacks in app, target '${parsed.pathOrId}' is missing a stack prefix. Use 'StackName:${parsed.pathOrId}' or 'StackName/...' (path form). Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
@@ -38480,7 +38481,7 @@ function pickStringArray$1(value) {
 	for (const v of value) if (typeof v === "string") out.push(v);
 	return out;
 }
-function notFoundError(target, stack, resources) {
+function notFoundError$1(target, stack, resources) {
 	const tasks = [];
 	for (const [logicalId, resource] of Object.entries(resources)) {
 		if (resource.Type !== "AWS::ECS::TaskDefinition") continue;
@@ -40432,20 +40433,74 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 	};
 	const integrationType = integration["Type"];
 	if (integrationType === "MOCK") {
-		const preflight = httpMethod === "OPTIONS" ? extractRestV1MockCorsConfig(integration) : void 0;
-		if (preflight) return [{
+		if (httpMethod === "OPTIONS") {
+			const preflight = extractRestV1MockCorsConfig(integration);
+			if (preflight) return [{
+				...baseRoute,
+				method: "OPTIONS",
+				pathPattern: path,
+				lambdaLogicalId: "",
+				mockCors: preflight
+			}];
+		}
+		const config = buildMockIntegrationConfig(integration);
+		return [{
 			...baseRoute,
-			method: "OPTIONS",
+			method: httpMethod,
 			pathPattern: path,
 			lambdaLogicalId: "",
-			mockCors: preflight
+			restV1Integration: config
+		}];
+	}
+	if (integrationType === "HTTP_PROXY") {
+		const config = buildHttpProxyIntegrationConfig(integration, stackName, logicalId);
+		if (config.kind === "unsupported") return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: "",
+			unsupported: { reason: config.reason }
+		}];
+		return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: "",
+			restV1Integration: config.config
+		}];
+	}
+	if (integrationType === "HTTP") {
+		const config = buildHttpIntegrationConfig(integration, stackName, logicalId);
+		if (config.kind === "unsupported") return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: "",
+			unsupported: { reason: config.reason }
 		}];
 		return [{
 			...baseRoute,
 			method: httpMethod,
 			pathPattern: path,
 			lambdaLogicalId: "",
-			unsupported: { reason: `${stackName}/${logicalId}: MOCK integration is not emulated (only the CORS preflight subset, where HttpMethod=OPTIONS and IntegrationResponses carry literal method.response.header.* values, is supported).` }
+			restV1Integration: config.config
+		}];
+	}
+	if (integrationType === "AWS") {
+		const config = buildAwsIntegrationConfig(integration, stackName, logicalId);
+		if (config.kind === "unsupported") return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: "",
+			unsupported: { reason: config.reason }
+		}];
+		return [{
+			...baseRoute,
+			method: httpMethod,
+			pathPattern: path,
+			lambdaLogicalId: config.config.lambdaLogicalId,
+			restV1Integration: config.config
 		}];
 	}
 	if (integrationType !== "AWS_PROXY") return [{
@@ -40453,7 +40508,7 @@ function discoverRestV1Method(logicalId, resource, template, stackName) {
 		method: httpMethod,
 		pathPattern: path,
 		lambdaLogicalId: "",
-		unsupported: { reason: `${stackName}/${logicalId}: REST v1 integration type '${String(integrationType)}' is not supported (only AWS_PROXY and the MOCK CORS preflight subset).` }
+		unsupported: { reason: `${stackName}/${logicalId}: unknown REST v1 integration type '${String(integrationType)}' (expected AWS_PROXY / AWS / HTTP / HTTP_PROXY / MOCK).` }
 	}];
 	const integrationUri = integration["Uri"];
 	const arnOutcome = resolveLambdaArnOutcome(integrationUri);
@@ -40523,6 +40578,188 @@ function extractRestV1MockCorsConfig(integration) {
 	};
 }
 /**
+* Marker sequence on a Lambda invoke ARN — used to tell apart REST v1
+* `AWS` integrations whose backend is Lambda (`functions/<arn>/invocations`)
+* from other AWS-service integrations (`:s3:path/...`, `:sqs:path/...`).
+* Closes #457's AWS-vs-Lambda discrimination.
+*/
+const LAMBDA_INVOKE_PATH = ":lambda:path/2015-03-31/functions/";
+/**
+* Build a MOCK integration config for `cdkd local start-api` dispatch.
+*
+* Pulls `Integration.RequestTemplates['application/json']` (drives MOCK
+* status-code selection — AWS reads `{"statusCode": N}` from the rendered
+* template) and `Integration.IntegrationResponses[]` (drives the shaped
+* response).
+*/
+function buildMockIntegrationConfig(integration) {
+	const requestTemplate = pickStringFromRecord(integration["RequestTemplates"], "application/json");
+	const responses = readIntegrationResponses(integration);
+	return {
+		kind: "mock",
+		requestTemplate: requestTemplate ?? void 0,
+		responses
+	};
+}
+/**
+* Build a HTTP_PROXY integration config. The Uri must be a literal
+* string at template-author time — `Fn::Sub` shapes with literal
+* placeholders are rare and unsupported in v1 (surfaces as a 501 with
+* a clear reason).
+*/
+function buildHttpProxyIntegrationConfig(integration, stackName, logicalId) {
+	const uri = integration["Uri"];
+	if (typeof uri !== "string" || uri.length === 0) return {
+		kind: "unsupported",
+		reason: `${stackName}/${logicalId}: HTTP_PROXY Integration.Uri must be a literal string in v1 (cdkd local start-api does not resolve Fn::Sub / Fn::Join in HTTP_PROXY Uris); got ${shortJson$1(uri)}.`
+	};
+	const integrationHttpMethod = pickStringField(integration, "IntegrationHttpMethod");
+	const requestParameters = pickStringRecord(integration["RequestParameters"]);
+	const responses = readIntegrationResponses(integration);
+	return {
+		kind: "config",
+		config: {
+			kind: "http-proxy",
+			uri,
+			...integrationHttpMethod !== void 0 && { integrationHttpMethod },
+			...requestParameters !== void 0 && { requestParameters },
+			responses
+		}
+	};
+}
+/**
+* Build an HTTP (non-proxy) integration config. Like HTTP_PROXY but with
+* `RequestTemplates` for VTL transformation.
+*/
+function buildHttpIntegrationConfig(integration, stackName, logicalId) {
+	const uri = integration["Uri"];
+	if (typeof uri !== "string" || uri.length === 0) return {
+		kind: "unsupported",
+		reason: `${stackName}/${logicalId}: HTTP Integration.Uri must be a literal string in v1 (cdkd local start-api does not resolve Fn::Sub / Fn::Join in HTTP Uris); got ${shortJson$1(uri)}.`
+	};
+	const integrationHttpMethod = pickStringField(integration, "IntegrationHttpMethod");
+	const requestParameters = pickStringRecord(integration["RequestParameters"]);
+	const requestTemplates = pickStringRecord(integration["RequestTemplates"]);
+	const responses = readIntegrationResponses(integration);
+	return {
+		kind: "config",
+		config: {
+			kind: "http",
+			uri,
+			...integrationHttpMethod !== void 0 && { integrationHttpMethod },
+			...requestParameters !== void 0 && { requestParameters },
+			...requestTemplates !== void 0 && { requestTemplates },
+			responses
+		}
+	};
+}
+/**
+* Build an AWS integration config. Branches on whether the integration
+* targets a Lambda (`:lambda:path/2015-03-31/functions/<arn>/invocations`)
+* or a non-Lambda AWS service (`:s3:path/...` / `:sqs:action/...` etc.).
+*
+* cdkd v1 supports Lambda non-proxy AWS integrations end-to-end. Non-
+* Lambda AWS service integrations surface as deferred-501 unsupported
+* routes — they would require an AWS SDK client per service, IAM
+* credential threading, and a sizable per-service unit-test matrix.
+* See [docs/local-emulation.md](docs/local-emulation.md) for the deferred
+* AWS-service-action list.
+*/
+function buildAwsIntegrationConfig(integration, stackName, logicalId) {
+	const uri = integration["Uri"];
+	if (!uriContainsLambdaMarker(uri)) return {
+		kind: "unsupported",
+		reason: `${stackName}/${logicalId}: REST v1 AWS integration targeting a non-Lambda service (Uri ${shortJson$1(uri)}) is not emulated locally in cdkd v1. Lambda non-proxy AWS integrations are supported; direct AWS service integrations (S3 / SQS / SNS / DynamoDB) require deploying to AWS. See docs/local-emulation.md.`
+	};
+	const arnOutcome = resolveLambdaArnOutcome(uri);
+	if (arnOutcome.kind === "unsupported") return {
+		kind: "unsupported",
+		reason: `${stackName}/${logicalId}.Integration.Uri: ${arnOutcome.detail} (got ${shortJson$1(uri)}). Lambda Arn intrinsics on cross-stack / imported references are not resolvable locally.`
+	};
+	const requestTemplates = pickStringRecord(integration["RequestTemplates"]);
+	const responses = readIntegrationResponses(integration);
+	return {
+		kind: "config",
+		config: {
+			kind: "aws-lambda",
+			lambdaLogicalId: arnOutcome.logicalId,
+			...requestTemplates !== void 0 && { requestTemplates },
+			responses
+		}
+	};
+}
+/**
+* Determine whether an `Integration.Uri` references a Lambda invoke path.
+* Recognises the canonical Lambda invoke ARN shape across the same
+* intrinsic forms `intrinsic-lambda-arn.ts` accepts (the shared resolver
+* never produces this Boolean directly, so we walk the shape here).
+*/
+function uriContainsLambdaMarker(uri) {
+	if (typeof uri === "string") return uri.includes(LAMBDA_INVOKE_PATH);
+	if (uri && typeof uri === "object" && !Array.isArray(uri)) {
+		const obj = uri;
+		if ("Fn::Sub" in obj) {
+			const v = obj["Fn::Sub"];
+			if (typeof v === "string") return v.includes(LAMBDA_INVOKE_PATH);
+			if (Array.isArray(v) && typeof v[0] === "string") return v[0].includes(LAMBDA_INVOKE_PATH);
+		}
+		if ("Fn::Join" in obj) {
+			const join = obj["Fn::Join"];
+			if (Array.isArray(join) && join.length === 2 && Array.isArray(join[1])) {
+				for (const piece of join[1]) if (typeof piece === "string" && piece.includes(LAMBDA_INVOKE_PATH)) return true;
+			}
+		}
+		if ("Ref" in obj || "Fn::GetAtt" in obj) return true;
+	}
+	return false;
+}
+/**
+* Read `Integration.IntegrationResponses[]` from a Method's Integration
+* sub-object and return the entries cdkd's dispatchers consume.
+*
+* Defensive: rejects non-object entries with a clear inline warning.
+*/
+function readIntegrationResponses(integration) {
+	const raw = integration["IntegrationResponses"];
+	if (!Array.isArray(raw)) return [];
+	const out = [];
+	for (const entry of raw) {
+		if (!entry || typeof entry !== "object") continue;
+		const obj = entry;
+		const statusCode = obj["StatusCode"];
+		if (statusCode === void 0) continue;
+		if (typeof statusCode !== "string" && typeof statusCode !== "number") continue;
+		const e = { StatusCode: String(statusCode) };
+		if (typeof obj["SelectionPattern"] === "string") e.SelectionPattern = obj["SelectionPattern"];
+		const responseParameters = pickStringRecord(obj["ResponseParameters"]);
+		if (responseParameters !== void 0) e.ResponseParameters = responseParameters;
+		const responseTemplates = pickStringRecord(obj["ResponseTemplates"]);
+		if (responseTemplates !== void 0) e.ResponseTemplates = responseTemplates;
+		if (typeof obj["ContentHandling"] === "string") e.ContentHandling = obj["ContentHandling"];
+		out.push(e);
+	}
+	return out;
+}
+function pickStringField(props, key) {
+	const v = props[key];
+	return typeof v === "string" ? v : void 0;
+}
+function pickStringRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const out = {};
+	let any = false;
+	for (const [k, v] of Object.entries(value)) if (typeof v === "string") {
+		out[k] = v;
+		any = true;
+	}
+	return any ? out : void 0;
+}
+function pickStringFromRecord(value, key) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const v = value[key];
+	return typeof v === "string" ? v : void 0;
+}
+/**
 * Walk a chain of `AWS::ApiGateway::Resource` parent pointers up to the
 * `RestApi` root to build the full path. Each `Resource` contributes a
 * `PathPart` segment; the `RestApi` itself contributes the leading `/`.
@@ -40890,6 +41127,1354 @@ function shortJson$1(value) {
 	}
 }
 
+//#endregion
+//#region src/local/vtl-engine.ts
+/** Error thrown when a template references an unsupported VTL feature. */
+var VtlEvaluationError = class VtlEvaluationError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "VtlEvaluationError";
+		Object.setPrototypeOf(this, VtlEvaluationError.prototype);
+	}
+};
+/** Built-in `$util` implementation. */
+function buildDefaultUtil() {
+	const coerce = (v) => {
+		if (v == null) return "";
+		if (typeof v === "string") return v;
+		if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+		try {
+			return JSON.stringify(v);
+		} catch {
+			return "";
+		}
+	};
+	return {
+		escapeJavaScript(input) {
+			return coerce(input).replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+		},
+		base64Encode(input) {
+			return Buffer.from(coerce(input), "utf-8").toString("base64");
+		},
+		base64Decode(input) {
+			return Buffer.from(coerce(input), "base64").toString("utf-8");
+		},
+		urlEncode(input) {
+			return encodeURIComponent(coerce(input));
+		},
+		urlDecode(input) {
+			try {
+				return decodeURIComponent(coerce(input));
+			} catch {
+				return coerce(input);
+			}
+		},
+		parseJson(input) {
+			const s = coerce(input);
+			try {
+				return JSON.parse(s);
+			} catch (err) {
+				throw new VtlEvaluationError(`$util.parseJson: invalid JSON input: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+	};
+}
+/**
+* Public entry point — evaluate a VTL template against a context and
+* return the rendered string. Throws {@link VtlEvaluationError} on any
+* unsupported syntax or runtime failure.
+*
+* Empty / undefined templates short-circuit to an empty string, matching
+* AWS API Gateway behavior when `RequestTemplates` / `ResponseTemplates`
+* is absent for the selected content type.
+*/
+function evaluateVtl(template, ctx) {
+	if (template === void 0 || template.length === 0) return "";
+	return new VtlEvaluator(ctx).evaluate(template);
+}
+/**
+* Stateful evaluator. Tokenizes + parses + renders in one pass — minimal
+* subset, so a recursive-descent walk over the template suffices. Tracks
+* a per-template scope chain for `#set` and `#foreach` bindings.
+*/
+var VtlEvaluator = class {
+	ctx;
+	scopes;
+	output = [];
+	constructor(ctx) {
+		this.ctx = ctx;
+		this.scopes = [/* @__PURE__ */ new Map()];
+	}
+	evaluate(template) {
+		this.renderBlock(template);
+		return this.output.join("");
+	}
+	/**
+	* Render a block — walks the template, interpolating `${var}` /
+	* `$var.field.method(args)` and handling `#set` / `#if` / `#foreach`
+	* directives.
+	*
+	* The walk is line-aware for directives: every `#directive` MUST start
+	* a line (after whitespace) per Velocity convention, but for ergonomics
+	* we also accept directives at the start of the template. Inline `$var`
+	* references are handled anywhere.
+	*/
+	renderBlock(block) {
+		let i = 0;
+		while (i < block.length) {
+			const ch = block[i];
+			if (ch === "#" && this.isDirectiveStart(block, i)) {
+				i = this.handleDirective(block, i);
+				continue;
+			}
+			if (ch === "$") {
+				const consumed = this.handleVariable(block, i);
+				if (consumed > 0) {
+					i += consumed;
+					continue;
+				}
+			}
+			if (ch === "\\" && i + 1 < block.length && block[i + 1] === "$") {
+				this.output.push("$");
+				i += 2;
+				continue;
+			}
+			this.output.push(ch ?? "");
+			i++;
+		}
+	}
+	isDirectiveStart(block, i) {
+		if (i + 1 >= block.length) return false;
+		const next = block[i + 1];
+		if (next === "#") return true;
+		return next !== void 0 && /[a-zA-Z]/.test(next);
+	}
+	/**
+	* Handle one directive (`#set`, `#if`, `#foreach`, etc.) — returns the
+	* NEW index in `block` (i.e. how far we consumed past the directive).
+	*/
+	handleDirective(block, start) {
+		if (block[start + 1] === "#") {
+			const eol = block.indexOf("\n", start);
+			return eol === -1 ? block.length : eol + 1;
+		}
+		const directiveMatch = /^#([a-zA-Z]+)/.exec(block.slice(start));
+		if (!directiveMatch) {
+			this.output.push("#");
+			return start + 1;
+		}
+		const name = directiveMatch[1];
+		const afterDirective = start + 1 + name.length;
+		switch (name) {
+			case "set": return this.handleSetDirective(block, afterDirective);
+			case "if": return this.handleIfDirective(block, afterDirective);
+			case "foreach": return this.handleForeachDirective(block, afterDirective);
+			case "else":
+			case "elseif":
+			case "end": throw new VtlEvaluationError(`Unexpected #${name} outside of a #if / #foreach block`);
+			default: throw new VtlEvaluationError(`Unsupported VTL directive #${name} (cdkd local start-api supports #set / #if / #elseif / #else / #foreach / #end / ##)`);
+		}
+	}
+	/**
+	* `#set($var = expression)` — assigns to the innermost scope.
+	*/
+	handleSetDirective(block, after) {
+		const { args, end } = this.readParenArgs(block, after);
+		const eq = args.indexOf("=");
+		if (eq === -1) throw new VtlEvaluationError(`#set requires '=': got #set(${args})`);
+		const left = args.slice(0, eq).trim();
+		const right = args.slice(eq + 1).trim();
+		if (!left.startsWith("$")) throw new VtlEvaluationError(`#set left side must be a $var reference (got '${left}')`);
+		const varName = left.slice(1).replace(/^\{/, "").replace(/\}$/, "");
+		const value = this.evaluateExpression(right);
+		this.scopes[this.scopes.length - 1].set(varName, value);
+		return this.skipDirectiveTrailingNewline(block, end);
+	}
+	/**
+	* `#if (cond) ... #elseif (cond) ... #else ... #end`. Renders the
+	* first true branch only; the rest are skipped (their text NOT emitted).
+	*/
+	handleIfDirective(block, after) {
+		const { args: condExpr, end } = this.readParenArgs(block, after);
+		let rendered = false;
+		let renderedAny = false;
+		const branches = [{
+			condition: condExpr,
+			bodyStart: this.skipDirectiveTrailingNewline(block, end),
+			bodyEnd: -1
+		}];
+		let cursor = branches[0].bodyStart;
+		let depth = 1;
+		while (cursor < block.length && depth > 0) {
+			if (block[cursor] !== "#") {
+				cursor++;
+				continue;
+			}
+			const m = /^#([a-zA-Z]+)/.exec(block.slice(cursor));
+			if (!m) {
+				cursor++;
+				continue;
+			}
+			const tag = m[1];
+			const tagAfter = cursor + 1 + tag.length;
+			if (tag === "if" || tag === "foreach") {
+				depth++;
+				cursor = tagAfter;
+				continue;
+			}
+			if (tag === "end") {
+				depth--;
+				if (depth === 0) {
+					branches[branches.length - 1].bodyEnd = cursor;
+					const endIdx = this.skipDirectiveTrailingNewline(block, tagAfter);
+					for (const branch of branches) {
+						if (rendered) break;
+						const truthy = branch.condition === null ? !renderedAny : this.evaluateCondition(branch.condition);
+						if (truthy) {
+							this.renderBlock(block.slice(branch.bodyStart, branch.bodyEnd));
+							rendered = true;
+						}
+						renderedAny = renderedAny || truthy;
+					}
+					return endIdx;
+				}
+				cursor = tagAfter;
+				continue;
+			}
+			if (depth === 1 && (tag === "elseif" || tag === "else")) {
+				branches[branches.length - 1].bodyEnd = cursor;
+				if (tag === "elseif") {
+					const { args, end: elseifEnd } = this.readParenArgs(block, tagAfter);
+					branches.push({
+						condition: args,
+						bodyStart: this.skipDirectiveTrailingNewline(block, elseifEnd),
+						bodyEnd: -1
+					});
+					cursor = branches[branches.length - 1].bodyStart;
+				} else {
+					branches.push({
+						condition: null,
+						bodyStart: this.skipDirectiveTrailingNewline(block, tagAfter),
+						bodyEnd: -1
+					});
+					cursor = branches[branches.length - 1].bodyStart;
+				}
+				continue;
+			}
+			cursor = tagAfter;
+		}
+		throw new VtlEvaluationError("#if without matching #end");
+	}
+	/**
+	* `#foreach($x in $list) ... #end` — iterates a list / object's values.
+	*/
+	handleForeachDirective(block, after) {
+		const { args, end } = this.readParenArgs(block, after);
+		const m = /^\s*\$([a-zA-Z_][a-zA-Z_0-9]*)\s+in\s+(.+)$/.exec(args);
+		if (!m) throw new VtlEvaluationError(`Invalid #foreach syntax: ${args}`);
+		const varName = m[1];
+		const listExpr = m[2];
+		const listValue = this.evaluateExpression(listExpr);
+		let depth = 1;
+		let cursor = this.skipDirectiveTrailingNewline(block, end);
+		const bodyStart = cursor;
+		while (cursor < block.length && depth > 0) {
+			if (block[cursor] !== "#") {
+				cursor++;
+				continue;
+			}
+			const tm = /^#([a-zA-Z]+)/.exec(block.slice(cursor));
+			if (!tm) {
+				cursor++;
+				continue;
+			}
+			const tag = tm[1];
+			if (tag === "if" || tag === "foreach") {
+				depth++;
+				cursor += 1 + tag.length;
+				continue;
+			}
+			if (tag === "end") {
+				depth--;
+				if (depth === 0) {
+					const bodyEnd = cursor;
+					const endIdx = this.skipDirectiveTrailingNewline(block, cursor + 1 + tag.length);
+					const items = this.coerceToIterable(listValue);
+					for (const item of items) {
+						this.scopes.push(new Map([[varName, item]]));
+						try {
+							this.renderBlock(block.slice(bodyStart, bodyEnd));
+						} finally {
+							this.scopes.pop();
+						}
+					}
+					return endIdx;
+				}
+			}
+			cursor += 1 + tag.length;
+		}
+		throw new VtlEvaluationError("#foreach without matching #end");
+	}
+	/** Convert a value into an iterable sequence for `#foreach`. */
+	coerceToIterable(value) {
+		if (Array.isArray(value)) return value;
+		if (value && typeof value === "object") return Object.values(value);
+		if (value == null) return [];
+		return [value];
+	}
+	/**
+	* Skip whitespace and a single trailing newline immediately after a
+	* directive — matches Velocity's "directive eats its own newline"
+	* convention. Without this rule, every `#set(...)` line in a template
+	* would leave a blank line in the output.
+	*/
+	skipDirectiveTrailingNewline(block, after) {
+		let i = after;
+		while (i < block.length && (block[i] === " " || block[i] === "	")) i++;
+		if (block[i] === "\r") i++;
+		if (block[i] === "\n") i++;
+		return i;
+	}
+	/**
+	* Read `(...)` arguments after a directive name. Returns the inner
+	* string + the index AFTER the closing paren. Handles nested parens
+	* inside string literals / method calls.
+	*/
+	readParenArgs(block, after) {
+		let i = after;
+		while (i < block.length && (block[i] === " " || block[i] === "	")) i++;
+		if (block[i] !== "(") throw new VtlEvaluationError(`Expected '(' after directive at offset ${after}`);
+		i++;
+		let depth = 1;
+		const start = i;
+		let inString = null;
+		while (i < block.length && depth > 0) {
+			const c = block[i];
+			if (inString) {
+				if (c === "\\" && i + 1 < block.length) {
+					i += 2;
+					continue;
+				}
+				if (c === inString) inString = null;
+				i++;
+				continue;
+			}
+			if (c === "\"" || c === "'") {
+				inString = c;
+				i++;
+				continue;
+			}
+			if (c === "(") depth++;
+			else if (c === ")") depth--;
+			if (depth === 0) break;
+			i++;
+		}
+		if (depth !== 0) throw new VtlEvaluationError(`Unterminated parenthesised argument at offset ${after}`);
+		return {
+			args: block.slice(start, i),
+			end: i + 1
+		};
+	}
+	/**
+	* Handle a `$var` / `${var}` / `$obj.field.method(args)` reference.
+	* Returns the number of characters consumed (0 if not a reference —
+	* caller emits the literal `$`).
+	*/
+	handleVariable(block, start) {
+		const m = /^\$(\{[^}]+\}|[a-zA-Z_][a-zA-Z_0-9]*(?:\.[a-zA-Z_][a-zA-Z_0-9]*)*)/.exec(block.slice(start));
+		if (!m) return 0;
+		const ref = m[1];
+		const refStr = ref.startsWith("{") ? ref.slice(1, -1) : ref;
+		let consumed = m[0].length;
+		let value = this.resolveReference(refStr);
+		let pos = start + consumed;
+		while (pos < block.length) {
+			if (block[pos] === "(") {
+				const { args, end } = this.readParenArgs(block, pos);
+				value = this.callValueAsMethod(value, args, refStr);
+				consumed = end - start;
+				pos = end;
+				if (pos < block.length && block[pos] === ".") {
+					const tailMatch = /^\.([a-zA-Z_][a-zA-Z_0-9]*)/.exec(block.slice(pos));
+					if (tailMatch) {
+						const field = tailMatch[1];
+						value = lookupField(value, field);
+						consumed += tailMatch[0].length;
+						pos += tailMatch[0].length;
+						continue;
+					}
+				}
+				break;
+			}
+			break;
+		}
+		this.output.push(this.stringifyForOutput(value));
+		return consumed;
+	}
+	/**
+	* Resolve a dotted reference path against context + scopes. The first
+	* segment is matched against built-in roots (`input` / `context` / `util`
+	* / `inputRoot`) and the scope chain in order.
+	*/
+	resolveReference(path) {
+		const parts = path.split(".");
+		const first = parts[0];
+		const rest = parts.slice(1);
+		let base;
+		if (first === "input") base = this.ctx.input;
+		else if (first === "context") base = this.ctx.context;
+		else if (first === "util") base = this.ctx.util;
+		else if (first === "inputRoot") base = this.ctx.inputRoot;
+		else {
+			let found = false;
+			for (let i = this.scopes.length - 1; i >= 0; i--) {
+				const scope = this.scopes[i];
+				if (scope.has(first)) {
+					base = scope.get(first);
+					found = true;
+					break;
+				}
+			}
+			if (!found) return null;
+		}
+		return rest.reduce((acc, seg) => lookupField(acc, seg), base);
+	}
+	/**
+	* Invoke a value as a method — used after a `$ref(args)` shape. The
+	* value must be a function or a special-cased built-in.
+	*/
+	callValueAsMethod(value, argsRaw, refPath) {
+		if (typeof value !== "function") throw new VtlEvaluationError(`Reference '$${refPath}' is not callable (got ${typeof value}). cdkd supports calling $input / $util / $context method-style references only.`);
+		return value(...this.parseArgList(argsRaw));
+	}
+	/**
+	* Parse a comma-separated argument list — recursively evaluates each
+	* expression. Handles string literals, numbers, booleans, and nested
+	* `$var` refs.
+	*/
+	parseArgList(raw) {
+		const trimmed = raw.trim();
+		if (trimmed.length === 0) return [];
+		const parts = [];
+		let depth = 0;
+		let inString = null;
+		let start = 0;
+		for (let i = 0; i < trimmed.length; i++) {
+			const c = trimmed[i];
+			if (inString) {
+				if (c === "\\" && i + 1 < trimmed.length) {
+					i++;
+					continue;
+				}
+				if (c === inString) inString = null;
+				continue;
+			}
+			if (c === "\"" || c === "'") {
+				inString = c;
+				continue;
+			}
+			if (c === "(" || c === "[") depth++;
+			else if (c === ")" || c === "]") depth--;
+			else if (c === "," && depth === 0) {
+				parts.push(trimmed.slice(start, i));
+				start = i + 1;
+			}
+		}
+		parts.push(trimmed.slice(start));
+		return parts.map((p) => this.evaluateExpression(p.trim()));
+	}
+	/**
+	* Evaluate a sub-expression (string literal / number / boolean / null /
+	* `$ref` / `$ref.field`). Tiny grammar — no arithmetic operators.
+	*/
+	evaluateExpression(expr) {
+		const trimmed = expr.trim();
+		if (trimmed.length === 0) return null;
+		if (trimmed === "true") return true;
+		if (trimmed === "false") return false;
+		if (trimmed === "null") return null;
+		if (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'")) return this.unescapeStringLiteral(trimmed.slice(1, -1));
+		if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) return Number(trimmed);
+		if (trimmed.startsWith("$")) {
+			const refMatch = /^\$(\{[^}]+\}|[a-zA-Z_][a-zA-Z_0-9]*(?:\.[a-zA-Z_][a-zA-Z_0-9]*)*)$/.exec(trimmed);
+			if (refMatch) {
+				const refStr = refMatch[1];
+				const refPath = refStr.startsWith("{") ? refStr.slice(1, -1) : refStr;
+				return this.resolveReference(refPath);
+			}
+			const callMatch = /^\$([a-zA-Z_][a-zA-Z_0-9]*(?:\.[a-zA-Z_][a-zA-Z_0-9]*)*)\((.*)\)$/.exec(trimmed);
+			if (callMatch) {
+				const refPath = callMatch[1];
+				const argsRaw = callMatch[2];
+				const value = this.resolveReference(refPath);
+				return this.callValueAsMethod(value, argsRaw, refPath);
+			}
+		}
+		throw new VtlEvaluationError(`Could not evaluate VTL sub-expression: '${trimmed}'`);
+	}
+	unescapeStringLiteral(s) {
+		return s.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\\\/g, "\\").replace(/\\"/g, "\"").replace(/\\'/g, "'");
+	}
+	/**
+	* Evaluate a `#if` / `#elseif` condition expression. Supports `&&`,
+	* `||`, `!`, comparison ops, and bare value tests (truthy/falsy).
+	*/
+	evaluateCondition(expr) {
+		const trimmed = expr.trim();
+		const orParts = splitTopLevel(trimmed, "||");
+		if (orParts.length > 1) return orParts.some((p) => this.evaluateCondition(p));
+		const andParts = splitTopLevel(trimmed, "&&");
+		if (andParts.length > 1) return andParts.every((p) => this.evaluateCondition(p));
+		if (trimmed.startsWith("!")) return !this.evaluateCondition(trimmed.slice(1).trim());
+		if (trimmed.startsWith("(") && trimmed.endsWith(")")) return this.evaluateCondition(trimmed.slice(1, -1));
+		for (const op of [
+			"==",
+			"!=",
+			"<=",
+			">=",
+			"<",
+			">"
+		]) {
+			const parts = splitTopLevel(trimmed, op);
+			if (parts.length === 2) return compareValues(this.evaluateExpression(parts[0]), this.evaluateExpression(parts[1]), op);
+		}
+		return isTruthy(this.evaluateExpression(trimmed));
+	}
+	/**
+	* Convert a value to its template output form. Mirrors Velocity's
+	* `toString` convention: `null` → empty string; objects → JSON; numbers
+	* / booleans → standard.
+	*/
+	stringifyForOutput(value) {
+		if (value === null || value === void 0) return "";
+		if (typeof value === "string") return value;
+		if (typeof value === "number" || typeof value === "boolean") return String(value);
+		return JSON.stringify(value);
+	}
+};
+/**
+* Look up `field` on `obj`. Returns `null` for missing fields (Velocity
+* silent-undefined convention).
+*/
+function lookupField(obj, field) {
+	if (obj == null) return null;
+	if (typeof obj === "object") {
+		const rec = obj;
+		if (Object.prototype.hasOwnProperty.call(rec, field)) return rec[field];
+		return null;
+	}
+	return null;
+}
+function splitTopLevel(s, sep) {
+	const out = [];
+	let depth = 0;
+	let inString = null;
+	let start = 0;
+	for (let i = 0; i < s.length; i++) {
+		const c = s[i];
+		if (inString) {
+			if (c === "\\" && i + 1 < s.length) {
+				i++;
+				continue;
+			}
+			if (c === inString) inString = null;
+			continue;
+		}
+		if (c === "\"" || c === "'") {
+			inString = c;
+			continue;
+		}
+		if (c === "(" || c === "[") depth++;
+		else if (c === ")" || c === "]") depth--;
+		else if (depth === 0 && s.startsWith(sep, i)) {
+			out.push(s.slice(start, i));
+			start = i + sep.length;
+			i += sep.length - 1;
+		}
+	}
+	out.push(s.slice(start));
+	return out;
+}
+function compareValues(lhs, rhs, op) {
+	if (op === "==") return looseEqual(lhs, rhs);
+	if (op === "!=") return !looseEqual(lhs, rhs);
+	const a = typeof lhs === "number" ? lhs : Number(lhs);
+	const b = typeof rhs === "number" ? rhs : Number(rhs);
+	if (Number.isFinite(a) && Number.isFinite(b)) switch (op) {
+		case "<": return a < b;
+		case "<=": return a <= b;
+		case ">": return a > b;
+		case ">=": return a >= b;
+	}
+	const sa = String(lhs);
+	const sb = String(rhs);
+	switch (op) {
+		case "<": return sa < sb;
+		case "<=": return sa <= sb;
+		case ">": return sa > sb;
+		case ">=": return sa >= sb;
+	}
+}
+function looseEqual(a, b) {
+	if (a === b) return true;
+	if (a == null || b == null) return a == null && b == null;
+	if (typeof a === typeof b) {
+		if (typeof a === "object") return JSON.stringify(a) === JSON.stringify(b);
+		return false;
+	}
+	return safeStringify(a) === safeStringify(b);
+}
+function safeStringify(v) {
+	if (v == null) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return "";
+	}
+}
+function isTruthy(v) {
+	if (v == null) return false;
+	if (typeof v === "boolean") return v;
+	if (typeof v === "number") return v !== 0;
+	if (typeof v === "string") return v.length > 0;
+	if (Array.isArray(v)) return v.length > 0;
+	if (typeof v === "object") return Object.keys(v).length > 0;
+	return true;
+}
+/**
+* Build a `VtlInput` binding from an HTTP request snapshot + matched
+* route context. `$input` exposes the body + parameter accessors used by
+* AWS API Gateway's VTL templates.
+*
+* `params()` returns the union of header / querystring / path maps;
+* `params(name)` resolves first against path, then querystring, then
+* header (matches AWS-deployed precedence).
+*
+* `json(jsonPath)` returns a JSON-stringified slice of the parsed body;
+* `path(jsonPath)` returns the raw native value (primitives unquoted).
+*
+* JSONPath support is minimal: supports `$` (root), `$.field`,
+* `$.field.subField`, `$.array[0]`. AWS supports more (filter
+* expressions, recursive descent); cdkd surfaces a clear error on
+* unsupported expressions rather than silently producing wrong output.
+*/
+function buildVtlInput(body, headers, querystring, pathParams) {
+	let jsonBodyCache;
+	let jsonBodyParsed = false;
+	function lazyJson() {
+		if (!jsonBodyParsed) {
+			jsonBodyParsed = true;
+			try {
+				jsonBodyCache = body.length === 0 ? null : JSON.parse(body);
+			} catch {
+				jsonBodyCache = null;
+			}
+		}
+		return jsonBodyCache;
+	}
+	function jsonFn(...args) {
+		const expr = args.length > 0 ? String(args[0]) : "$";
+		const val = applyJsonPath(lazyJson(), expr);
+		return JSON.stringify(val ?? null);
+	}
+	function pathFn(...args) {
+		const expr = args.length > 0 ? String(args[0]) : "$";
+		return applyJsonPath(lazyJson(), expr);
+	}
+	function paramsFn(...args) {
+		if (args.length === 0) return {
+			header: headers,
+			querystring,
+			path: pathParams
+		};
+		const arg = String(args[0]);
+		if (arg === "header") return headers;
+		if (arg === "querystring") return querystring;
+		if (arg === "path") return pathParams;
+		if (Object.prototype.hasOwnProperty.call(pathParams, arg)) return pathParams[arg];
+		if (Object.prototype.hasOwnProperty.call(querystring, arg)) return querystring[arg];
+		if (Object.prototype.hasOwnProperty.call(headers, arg)) return headers[arg];
+		const lowerArg = arg.toLowerCase();
+		for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === lowerArg) return v;
+		return null;
+	}
+	return {
+		body,
+		get jsonBody() {
+			return lazyJson();
+		},
+		headers,
+		querystring,
+		path: pathParams,
+		json: jsonFn,
+		path: pathFn,
+		params: paramsFn
+	};
+}
+/**
+* Minimal JSONPath evaluator. Supports `$`, `$.field`, `$.field.sub`,
+* `$.array[index]`. Unsupported syntax throws so the user sees a clear
+* pointer to the gap.
+*/
+function applyJsonPath(root, expr) {
+	const trimmed = expr.trim();
+	if (trimmed === "$" || trimmed.length === 0) return root;
+	if (!trimmed.startsWith("$")) throw new VtlEvaluationError(`JSONPath must start with '$': got '${trimmed}'`);
+	let cursor = root;
+	let i = 1;
+	while (i < trimmed.length) {
+		const c = trimmed[i];
+		if (c === ".") {
+			i++;
+			const m = /^[a-zA-Z_][a-zA-Z_0-9]*/.exec(trimmed.slice(i));
+			if (!m) throw new VtlEvaluationError(`Unsupported JSONPath syntax at position ${i}: '${trimmed}' (cdkd supports $, $.field, $.field.sub, $.array[index] only).`);
+			cursor = lookupField(cursor, m[0]);
+			i += m[0].length;
+			continue;
+		}
+		if (c === "[") {
+			const close = trimmed.indexOf("]", i);
+			if (close === -1) throw new VtlEvaluationError(`Unterminated [ in JSONPath: '${trimmed}'`);
+			const inside = trimmed.slice(i + 1, close).trim();
+			if (/^-?\d+$/.test(inside)) {
+				const idx = Number(inside);
+				if (Array.isArray(cursor)) cursor = cursor[idx];
+				else cursor = null;
+			} else if (inside.startsWith("\"") && inside.endsWith("\"") || inside.startsWith("'") && inside.endsWith("'")) cursor = lookupField(cursor, inside.slice(1, -1));
+			else throw new VtlEvaluationError(`Unsupported JSONPath bracket expression: '${inside}' (cdkd supports integer indices and quoted string keys only).`);
+			i = close + 1;
+			continue;
+		}
+		throw new VtlEvaluationError(`Unexpected character in JSONPath at position ${i}: '${trimmed}'`);
+	}
+	return cursor;
+}
+/**
+* Build a `$context` binding from a request snapshot + matched route.
+* The mapping mirrors what AWS API Gateway exposes (see AWS docs:
+* https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html).
+*/
+function buildVtlRequestContext(args) {
+	return {
+		requestId: args.requestId,
+		httpMethod: args.httpMethod,
+		resourcePath: args.resourcePath,
+		stage: args.stage,
+		identity: {
+			sourceIp: args.sourceIp,
+			userAgent: args.userAgent
+		}
+	};
+}
+
+//#endregion
+//#region src/local/integration-response-selector.ts
+/**
+* Pick the right `IntegrationResponses[]` entry for the given outcome.
+*
+* Per AWS docs, `SelectionPattern` is matched against the backend
+* outcome regardless of whether the backend returned success or error —
+* a `SelectionPattern: '200'` entry IS expected to match an HTTP 200
+* upstream response. cdkd ALWAYS runs the regex loop first and only
+* falls to the default entry when no pattern matches; pre-#505-review
+* the success branch short-circuited to the default entry without
+* running the regex loop, which silently dropped success-side selection.
+*
+* @param entries - The `IntegrationResponses[]` array from the template
+*   (already extracted from the route's Integration property).
+* @param matchTarget - The string AWS would match `SelectionPattern`
+*   against. For HTTP / HTTP_PROXY this is `String(upstream.status)`;
+*   for Lambda this is the `errorMessage` field on the parsed payload,
+*   or the sentinel `'success'` when the payload has no `errorMessage`.
+*   For MOCK this is unused (MOCK dispatch picks by `StatusCode`).
+* @param fallbackStatusCode - Status code to use when `entries` is empty
+*   or no entry matches AND no default entry exists. HTTP / HTTP_PROXY
+*   pass the upstream status; Lambda passes 200 on success / 500 on
+*   error.
+*/
+function selectIntegrationResponse(entries, matchTarget, fallbackStatusCode = 200) {
+	if (!entries || entries.length === 0) return {
+		entry: null,
+		statusCode: fallbackStatusCode
+	};
+	const defaultEntry = entries.find((e) => e.SelectionPattern === void 0 || e.SelectionPattern === "");
+	for (const entry of entries) {
+		if (entry.SelectionPattern === void 0 || entry.SelectionPattern === "") continue;
+		try {
+			if (new RegExp(`^${entry.SelectionPattern}$`).test(matchTarget)) return {
+				entry,
+				statusCode: parseStatus$1(entry.StatusCode, fallbackStatusCode)
+			};
+		} catch {}
+	}
+	const entry = defaultEntry ?? null;
+	return {
+		entry,
+		statusCode: entry !== null ? parseStatus$1(entry.StatusCode, fallbackStatusCode) : fallbackStatusCode
+	};
+}
+function parseStatus$1(raw, fallback) {
+	if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+	if (typeof raw === "string") {
+		const parsed = Number.parseInt(raw, 10);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+	return fallback;
+}
+/**
+* Evaluate `IntegrationResponse.ResponseParameters` — header literals
+* mapped onto the HTTP response. Returns `{name: value}` for every entry
+* we could resolve; unresolvable entries (non-literal / mapping
+* expression) get a warning via `onUnsupported` and are skipped.
+*
+* AWS format: keys are `method.response.header.<HeaderName>`; values
+* are `'literal'` (with single quotes) or mapping expressions
+* (`integration.response.body.X` / `integration.response.header.X` /
+* `context.X`). cdkd v1 supports the literal form only.
+*/
+function evaluateResponseParameters(responseParameters, opts = {}) {
+	if (!responseParameters) return {};
+	const out = {};
+	for (const [key, value] of Object.entries(responseParameters)) {
+		const headerMatch = /^method\.response\.header\.(.+)$/.exec(key);
+		if (!headerMatch) {
+			opts.onUnsupported?.(key, value, `Only method.response.header.<name> keys are supported on REST v1 ResponseParameters; cdkd cannot map ${key}.`);
+			continue;
+		}
+		const headerName = headerMatch[1];
+		if (typeof value !== "string") {
+			opts.onUnsupported?.(key, String(value), `non-string ResponseParameter value`);
+			continue;
+		}
+		if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+			out[headerName] = value.slice(1, -1);
+			continue;
+		}
+		opts.onUnsupported?.(key, value, `ResponseParameter value '${value}' is a mapping expression (integration.response.* / context.*) which cdkd local start-api does not emulate. Only single-quoted literals are honored.`);
+	}
+	return out;
+}
+/**
+* Pick the response template AWS would render for the given Accept
+* header. AWS uses content negotiation; cdkd picks `application/json`
+* first, then any other entry. Returns `undefined` when no template is
+* configured (caller emits the backend body verbatim).
+*
+* The chosen template's content-type is also returned so the dispatcher
+* can emit a matching `Content-Type` header (matches AWS-deployed
+* behavior).
+*/
+function pickResponseTemplate(responseTemplates, accept) {
+	if (!responseTemplates) return void 0;
+	const entries = Object.entries(responseTemplates);
+	if (entries.length === 0) return void 0;
+	if (accept) {
+		const acceptTypes = accept.split(",").map((s) => s.split(";")[0].trim()).filter(Boolean);
+		for (const acceptType of acceptTypes) for (const [ct, template] of entries) if (ct === acceptType) return {
+			template,
+			contentType: ct
+		};
+	}
+	const jsonEntry = responseTemplates["application/json"];
+	if (jsonEntry !== void 0) return {
+		template: jsonEntry,
+		contentType: "application/json"
+	};
+	const first = entries[0];
+	return {
+		template: first[1],
+		contentType: first[0]
+	};
+}
+
+//#endregion
+//#region src/local/rest-v1-integrations.ts
+/**
+* Dispatch a MOCK integration. AWS MOCK semantics:
+*
+*   1. Render `RequestTemplates['application/json']` (VTL) against the
+*      request — yields a JSON object like `{"statusCode": 200}`.
+*   2. Parse the rendered JSON; pick the `IntegrationResponses[]` entry
+*      whose `StatusCode` equals the parsed `statusCode` (string compare,
+*      mirroring AWS).
+*   3. Render the picked entry's `ResponseTemplates[<content-type>]`
+*      against an empty body context and emit it.
+*   4. Apply `ResponseParameters` header literals.
+*
+* When no request template is configured AWS defaults to picking the
+* `IntegrationResponses[]` entry with `SelectionPattern === ''` (or the
+* first entry).
+*/
+function dispatchMockIntegration(config, req) {
+	const logger = getLogger().child("start-api");
+	const ctx = buildVtlContextFromRequest(req, "");
+	let pickedStatus;
+	if (config.requestTemplate !== void 0 && config.requestTemplate.trim().length > 0) try {
+		pickedStatus = extractStatusCodeFromRendered(evaluateVtl(config.requestTemplate, ctx));
+	} catch (err) {
+		return vtlFailure("request", err, config.requestTemplate);
+	}
+	let entry = null;
+	if (pickedStatus !== void 0) entry = config.responses.find((e) => parseStatus(e.StatusCode) === pickedStatus) ?? defaultResponseEntry(config.responses);
+	else entry = defaultResponseEntry(config.responses);
+	if (!entry) return {
+		statusCode: pickedStatus ?? 200,
+		headers: { "content-type": "application/json" },
+		body: ""
+	};
+	const accept = req.headers["accept"];
+	const picked = pickResponseTemplate(entry.ResponseTemplates, accept);
+	const respCtx = buildVtlContextFromRequest(req, "", null);
+	let body = "";
+	let contentType = "application/json";
+	if (picked) {
+		try {
+			body = evaluateVtl(picked.template, respCtx);
+		} catch (err) {
+			return vtlFailure("response", err, picked.template);
+		}
+		contentType = picked.contentType;
+	}
+	const headers = { "content-type": contentType };
+	Object.assign(headers, evaluateResponseParameters(entry.ResponseParameters, { onUnsupported: (_k, _v, reason) => logger.warn(`MOCK response: ${reason}`) }));
+	return {
+		statusCode: parseStatus(entry.StatusCode) ?? 200,
+		headers,
+		body
+	};
+}
+/**
+* Dispatch an HTTP_PROXY integration. The request is forwarded verbatim
+* with `RequestParameters` mappings applied; the response is also
+* forwarded verbatim (AWS does NOT apply ResponseTemplates on HTTP_PROXY,
+* only IntegrationResponses[].SelectionPattern routes the status code).
+*/
+async function dispatchHttpProxyIntegration(config, req, deps) {
+	const url = substituteUriPlaceholders(config.uri, req);
+	const method = config.integrationHttpMethod ?? req.method;
+	const outHeaders = { ...req.headers };
+	for (const drop of [
+		"host",
+		"connection",
+		"content-length",
+		"transfer-encoding"
+	]) delete outHeaders[drop];
+	applyRequestParameters(config.requestParameters, req, {
+		headers: outHeaders,
+		urlObj: void 0
+	});
+	const fetchImpl = deps.fetch ?? globalThis.fetch;
+	const fetchInit = {
+		method,
+		headers: outHeaders
+	};
+	if (req.body.length > 0) fetchInit.body = new Uint8Array(req.body);
+	let upstream;
+	try {
+		upstream = await fetchImpl(url, fetchInit);
+	} catch (err) {
+		return {
+			statusCode: 502,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				message: "HTTP_PROXY upstream unreachable",
+				url,
+				reason: err instanceof Error ? err.message : String(err)
+			})
+		};
+	}
+	const upstreamBody = Buffer.from(await upstream.arrayBuffer());
+	const selected = selectIntegrationResponse(config.responses, String(upstream.status), upstream.status);
+	const headers = {};
+	upstream.headers.forEach((value, name) => {
+		headers[name.toLowerCase()] = value;
+	});
+	delete headers["content-encoding"];
+	delete headers["content-length"];
+	const logger = getLogger().child("start-api");
+	Object.assign(headers, evaluateResponseParameters(selected.entry?.ResponseParameters, { onUnsupported: (_k, _v, reason) => logger.warn(`HTTP_PROXY response: ${reason}`) }));
+	return {
+		statusCode: selected.entry ? selected.statusCode : upstream.status,
+		headers,
+		body: upstreamBody
+	};
+}
+/**
+* Dispatch an HTTP (non-proxy) integration: HTTP_PROXY + VTL on both
+* directions. Same upstream-call shape; the request body is transformed
+* via VTL, and the response body is transformed via VTL too.
+*/
+async function dispatchHttpIntegration(config, req, deps) {
+	const logger = getLogger().child("start-api");
+	const url = substituteUriPlaceholders(config.uri, req);
+	const method = config.integrationHttpMethod ?? req.method;
+	const ctx = buildVtlContextFromRequest(req, req.body.toString("utf-8"));
+	const reqTemplate = pickRequestTemplate(config.requestTemplates, req.headers["content-type"]);
+	let outBody;
+	let outContentType = req.headers["content-type"] ?? "application/json";
+	if (reqTemplate) {
+		try {
+			outBody = evaluateVtl(reqTemplate.template, ctx);
+		} catch (err) {
+			return vtlFailure("request", err, reqTemplate.template);
+		}
+		outContentType = reqTemplate.contentType;
+	} else outBody = req.body.toString("utf-8");
+	const outHeaders = {
+		...req.headers,
+		"content-type": outContentType
+	};
+	for (const drop of [
+		"host",
+		"connection",
+		"content-length",
+		"transfer-encoding"
+	]) delete outHeaders[drop];
+	applyRequestParameters(config.requestParameters, req, {
+		headers: outHeaders,
+		urlObj: void 0
+	});
+	const fetchImpl = deps.fetch ?? globalThis.fetch;
+	const fetchInit = {
+		method,
+		headers: outHeaders
+	};
+	if (outBody !== void 0 && outBody.length > 0) fetchInit.body = outBody;
+	let upstream;
+	try {
+		upstream = await fetchImpl(url, fetchInit);
+	} catch (err) {
+		return {
+			statusCode: 502,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				message: "HTTP upstream unreachable",
+				url,
+				reason: err instanceof Error ? err.message : String(err)
+			})
+		};
+	}
+	const upstreamContentType = upstream.headers.get("content-type") ?? "application/octet-stream";
+	const isUpstreamTextLike = isTextLikeContentType(upstreamContentType);
+	let upstreamText;
+	let upstreamBinary;
+	if (isUpstreamTextLike) upstreamText = await upstream.text();
+	else upstreamBinary = Buffer.from(await upstream.arrayBuffer());
+	const selected = selectIntegrationResponse(config.responses, String(upstream.status), upstream.status);
+	let body;
+	let contentType = upstreamContentType;
+	if (selected.entry) {
+		const picked = pickResponseTemplate(selected.entry.ResponseTemplates, req.headers["accept"]);
+		if (picked) if (upstreamText === void 0) {
+			logger.warn(`HTTP response: ResponseTemplates set but upstream Content-Type '${upstreamContentType}' is binary; passing body through unchanged.`);
+			body = upstreamBinary;
+		} else {
+			const respCtx = buildVtlContextFromRequest(req, upstreamText, safeJsonParse(upstreamText));
+			try {
+				body = evaluateVtl(picked.template, respCtx);
+			} catch (err) {
+				return vtlFailure("response", err, picked.template);
+			}
+			contentType = picked.contentType;
+		}
+		else body = upstreamText ?? upstreamBinary;
+	} else body = upstreamText ?? upstreamBinary;
+	const headers = { "content-type": contentType };
+	Object.assign(headers, evaluateResponseParameters(selected.entry?.ResponseParameters, { onUnsupported: (_k, _v, reason) => logger.warn(`HTTP response: ${reason}`) }));
+	return {
+		statusCode: selected.statusCode,
+		headers,
+		body
+	};
+}
+/**
+* Dispatch an AWS (Lambda non-proxy) integration. The request body is
+* transformed via VTL into the Lambda event; the Lambda is invoked via
+* RIE; the return value is transformed via ResponseTemplates.
+*
+* AWS error routing: when the Lambda returns an object with an
+* `errorMessage` field (Node Lambda runtime convention), AWS treats it
+* as an error and matches `SelectionPattern` against the
+* `errorMessage`. Otherwise success.
+*/
+async function dispatchAwsLambdaIntegration(config, req, deps) {
+	const logger = getLogger().child("start-api");
+	const ctx = buildVtlContextFromRequest(req, req.body.toString("utf-8"));
+	const template = pickRequestTemplate(config.requestTemplates, req.headers["content-type"]);
+	let eventPayload;
+	if (template) {
+		let rendered;
+		try {
+			rendered = evaluateVtl(template.template, ctx);
+		} catch (err) {
+			return vtlFailure("request", err, template.template);
+		}
+		try {
+			eventPayload = JSON.parse(rendered);
+		} catch {
+			eventPayload = rendered;
+		}
+	} else eventPayload = safeJsonParse(req.body.toString("utf-8")) ?? req.body.toString("utf-8");
+	let handle;
+	try {
+		handle = await deps.pool.acquire(config.lambdaLogicalId);
+	} catch (err) {
+		return {
+			statusCode: 502,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				message: "Failed to acquire RIE container for AWS Lambda non-proxy integration",
+				reason: err instanceof Error ? err.message : String(err)
+			})
+		};
+	}
+	let invokeOutcome;
+	try {
+		invokeOutcome = await invokeRie(handle.containerHost, handle.hostPort, eventPayload, deps.rieTimeoutMs);
+	} catch (err) {
+		deps.pool.release(handle);
+		return {
+			statusCode: 502,
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				message: "AWS Lambda non-proxy invocation failed",
+				reason: err instanceof Error ? err.message : String(err)
+			})
+		};
+	}
+	deps.pool.release(handle);
+	const payload = invokeOutcome.payload;
+	const isError = payload !== null && typeof payload === "object" && "errorMessage" in payload;
+	const matchTarget = isError ? String(payload["errorMessage"]) : "success";
+	const selected = selectIntegrationResponse(config.responses, matchTarget, isError ? 500 : 200);
+	const respCtx = buildVtlContextFromRequest(req, JSON.stringify(payload ?? null), payload);
+	let body = "";
+	let contentType = "application/json";
+	if (selected.entry) {
+		const picked = pickResponseTemplate(selected.entry.ResponseTemplates, req.headers["accept"]);
+		if (picked) {
+			try {
+				body = evaluateVtl(picked.template, respCtx);
+			} catch (err) {
+				return vtlFailure("response", err, picked.template);
+			}
+			contentType = picked.contentType;
+		} else body = JSON.stringify(payload ?? null);
+	} else body = JSON.stringify(payload ?? null);
+	const headers = { "content-type": contentType };
+	Object.assign(headers, evaluateResponseParameters(selected.entry?.ResponseParameters, { onUnsupported: (_k, _v, reason) => logger.warn(`AWS Lambda non-proxy response: ${reason}`) }));
+	return {
+		statusCode: selected.statusCode,
+		headers,
+		body
+	};
+}
+function buildVtlContextFromRequest(req, body, inputRoot) {
+	return {
+		input: buildVtlInput(body, req.headers, req.querystring, req.pathParameters),
+		context: buildVtlRequestContext({
+			requestId: req.requestId,
+			httpMethod: req.method,
+			resourcePath: req.resourcePath,
+			stage: req.stage,
+			sourceIp: req.sourceIp,
+			userAgent: req.userAgent
+		}),
+		util: buildDefaultUtil(),
+		...inputRoot !== void 0 && { inputRoot }
+	};
+}
+function pickRequestTemplate(requestTemplates, contentType) {
+	if (!requestTemplates) return void 0;
+	const entries = Object.entries(requestTemplates);
+	if (entries.length === 0) return void 0;
+	if (contentType) {
+		const primary = contentType.split(";")[0].trim();
+		if (requestTemplates[primary] !== void 0) return {
+			template: requestTemplates[primary],
+			contentType: primary
+		};
+	}
+	if (requestTemplates["application/json"] !== void 0) return {
+		template: requestTemplates["application/json"],
+		contentType: "application/json"
+	};
+	const first = entries[0];
+	return {
+		template: first[1],
+		contentType: first[0]
+	};
+}
+/**
+* Extract `{"statusCode": <N>}` from a rendered MOCK request template.
+* AWS uses this single key to drive `IntegrationResponses[]` selection.
+*/
+function extractStatusCodeFromRendered(rendered) {
+	try {
+		const parsed = JSON.parse(rendered);
+		if (parsed && typeof parsed === "object" && "statusCode" in parsed) {
+			const val = parsed["statusCode"];
+			if (typeof val === "number") return val;
+			if (typeof val === "string") {
+				const n = Number.parseInt(val, 10);
+				if (Number.isFinite(n)) return n;
+			}
+		}
+	} catch {}
+}
+function defaultResponseEntry(entries) {
+	return entries.find((e) => e.SelectionPattern === void 0 || e.SelectionPattern === "") ?? null;
+}
+function parseStatus(raw) {
+	if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+	if (typeof raw === "string") {
+		const n = Number.parseInt(raw, 10);
+		if (Number.isFinite(n)) return n;
+	}
+}
+/**
+* Heuristic: is the given HTTP `Content-Type` header value likely to
+* carry text content that VTL ResponseTemplates can safely render
+* against? Used by `dispatchHttpIntegration` to branch the upstream
+* body read between `.text()` (text-like) and `.arrayBuffer()` (binary
+* pass-through). Charset parameters are stripped before matching.
+*
+* Exported for unit testing.
+*/
+function isTextLikeContentType(contentType) {
+	const primary = contentType.split(";")[0].trim().toLowerCase();
+	if (primary.startsWith("text/")) return true;
+	if (primary === "application/json" || primary === "application/xml" || primary === "application/x-www-form-urlencoded" || primary === "application/javascript" || primary === "application/ld+json") return true;
+	if (primary.startsWith("application/") && (primary.endsWith("+json") || primary.endsWith("+xml"))) return true;
+	return false;
+}
+/**
+* Classify a hostname or IP literal against well-known internal address
+* spaces. Used by `warnSsrfRiskyUri` at server boot to surface a warn
+* line per HTTP / HTTP_PROXY integration whose URI points at a
+* potentially-sensitive destination. Best-effort; does NOT do DNS
+* resolution — only matches hostname literals that are already an IP.
+*
+* Returns `undefined` when the host appears safe (public DNS name) OR
+* cannot be classified (DNS name that may resolve to an internal IP
+* the helper cannot see without async DNS).
+*
+* Exported for unit testing.
+*/
+function classifyInternalHost(host) {
+	const h = host.replace(/^\[|\]$/g, "");
+	if (h === "169.254.169.254" || h === "[fd00:ec2::254]" || h === "fd00:ec2::254") return "AWS IMDS (169.254.169.254) — credentials exfiltration risk";
+	if (/^127\.\d+\.\d+\.\d+$/.test(h)) return "IPv4 loopback (127.0.0.0/8)";
+	if (h === "::1") return "IPv6 loopback (::1)";
+	if (/^169\.254\.\d+\.\d+$/.test(h)) return "IPv4 link-local (169.254.0.0/16)";
+	if (/^fe[89ab][0-9a-f]?:/i.test(h)) return "IPv6 link-local (fe80::/10)";
+	if (/^10\.\d+\.\d+\.\d+$/.test(h)) return "RFC1918 private (10.0.0.0/8)";
+	if (/^192\.168\.\d+\.\d+$/.test(h)) return "RFC1918 private (192.168.0.0/16)";
+	const m = /^172\.(\d+)\.\d+\.\d+$/.exec(h);
+	if (m && Number(m[1]) >= 16 && Number(m[1]) <= 31) return "RFC1918 private (172.16.0.0/12)";
+}
+/**
+* Emit a `logger.warn` line for each HTTP / HTTP_PROXY integration
+* whose `Integration.Uri` parses to a hostname classified as internal
+* by `classifyInternalHost`. Called once at server boot from
+* `cdkd local start-api`'s discovery pass; per-route deduplicated.
+*
+* cdkd does NOT block the URI — this is a developer-loop tool, not a
+* security boundary, and warn-and-proceed matches the precedent set by
+* the cognito JWKS pass-through fallback. The right v2 follow-up is an
+* `--allow-internal-uri` flag (and an opposite default block) once the
+* surface is well-understood.
+*/
+function warnSsrfRiskyUri(uri, routeLabel, warn) {
+	let host;
+	try {
+		const sanitized = uri.replace(/\{[^/{}]+\}/g, "x");
+		host = new URL(sanitized).hostname;
+	} catch {
+		return;
+	}
+	const classification = classifyInternalHost(host);
+	if (classification !== void 0) warn(`Integration URI for ${routeLabel} points at ${host} — ${classification}. cdkd does NOT block this; ensure the upstream is intentional.`);
+}
+function safeJsonParse(s) {
+	try {
+		return JSON.parse(s);
+	} catch {
+		return null;
+	}
+}
+/**
+* Apply `Integration.RequestParameters` mappings — header / query / path
+* rewrites that copy from `method.request.X` to `integration.request.Y`.
+*
+* Supported key shapes:
+*   - `integration.request.header.<name>` → outgoing header
+*   - `integration.request.querystring.<name>` → query string param
+*   - `integration.request.path.<name>` → path placeholder substitution
+*
+* Supported value shapes:
+*   - `method.request.header.<name>` → read incoming header
+*   - `method.request.querystring.<name>` → read incoming query param
+*   - `method.request.path.<name>` → read path parameter
+*   - `'literal'` → single-quoted literal
+*
+* Unsupported mapping expressions are logged at warn and skipped (matches
+* the ResponseParameters handling in `integration-response-selector.ts`).
+*/
+function applyRequestParameters(requestParameters, req, out) {
+	if (!requestParameters) return;
+	const logger = getLogger().child("start-api");
+	for (const [key, value] of Object.entries(requestParameters)) {
+		const resolved = resolveRequestParameterValue(value, req);
+		if (resolved === void 0) {
+			logger.warn(`RequestParameter '${key}' value '${value}' is not a recognized mapping; skipping.`);
+			continue;
+		}
+		const headerMatch = /^integration\.request\.header\.(.+)$/.exec(key);
+		const queryMatch = /^integration\.request\.querystring\.(.+)$/.exec(key);
+		const pathMatch = /^integration\.request\.path\.(.+)$/.exec(key);
+		if (headerMatch) out.headers[headerMatch[1].toLowerCase()] = resolved;
+		else if (queryMatch) logger.warn(`RequestParameter '${key}' (querystring rewrite) is recognized but cdkd applies querystring rewrites only via URI placeholder substitution; ignoring.`);
+		else if (pathMatch) logger.warn(`RequestParameter '${key}' (path rewrite) is recognized but cdkd substitutes path placeholders via {param} in the URI; ignoring.`);
+		else logger.warn(`Unsupported RequestParameter key '${key}'; skipping.`);
+	}
+}
+function resolveRequestParameterValue(raw, req) {
+	if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'")) return raw.slice(1, -1);
+	const headerMatch = /^method\.request\.header\.(.+)$/.exec(raw);
+	if (headerMatch) return req.headers[headerMatch[1].toLowerCase()];
+	const queryMatch = /^method\.request\.querystring\.(.+)$/.exec(raw);
+	if (queryMatch) return req.querystring[queryMatch[1]];
+	const pathMatch = /^method\.request\.path\.(.+)$/.exec(raw);
+	if (pathMatch) return req.pathParameters[pathMatch[1]];
+}
+/**
+* Substitute `{paramName}` placeholders in a URI string with the value
+* of the matching path parameter on the request. Used by HTTP_PROXY /
+* HTTP integrations whose `Integration.Uri` may contain such
+* placeholders (e.g. `https://upstream.example.com/users/{userId}`).
+*/
+function substituteUriPlaceholders(uri, req) {
+	return uri.replace(/\{([^/{}]+)\}/g, (_, name) => {
+		const val = req.pathParameters[name];
+		return val !== void 0 ? encodeURIComponent(val) : "";
+	});
+}
+function vtlFailure(direction, err, template) {
+	const reason = err instanceof VtlEvaluationError ? err.message : err instanceof Error ? err.message : String(err);
+	return {
+		statusCode: 502,
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			message: `VTL ${direction}-template evaluation failed`,
+			reason,
+			template: template.length > 200 ? template.slice(0, 200) + "..." : template
+		})
+	};
+}
+
 //#endregion
 //#region src/local/container-pool.ts
 const DEFAULT_IDLE_MS = 6e4;
@@ -43870,6 +45455,16 @@ async function handleRequest(req, res, state, opts) {
 		const overlay = buildOverlay(authorizer, authResult);
 		if (overlay) baseEvent = applyAuthorizerOverlay(baseEvent, overlay);
 	}
+	if (match.route.restV1Integration) {
+		try {
+			writeIntegrationOutcome(res, await dispatchRestV1Integration(match.route.restV1Integration, snapshot, matchCtx, state, opts));
+		} catch (err) {
+			logger.error(`REST v1 ${match.route.restV1Integration.kind} dispatch failed for ${match.route.declaredAt}: ${err instanceof Error ? err.message : String(err)}`);
+			if (!res.headersSent) writeError(res, 502);
+			else res.end();
+		}
+		return;
+	}
 	let handle;
 	try {
 		handle = await state.pool.acquire(match.route.lambdaLogicalId);
@@ -43949,6 +45544,50 @@ function writeStreamingResponse(res, result, releasePool) {
 	body.pipe(res);
 }
 /**
+* Dispatch a REST v1 non-AWS_PROXY integration to the matching handler.
+* Built once per request from the matched route + request snapshot.
+*
+* Returns a {@link RestV1IntegrationOutcome} — the caller writes it
+* onto the `ServerResponse` via {@link writeIntegrationOutcome}.
+*/
+async function dispatchRestV1Integration(integration, snapshot, matchCtx, state, opts) {
+	const headers = lowercaseSingularHeaders(snapshot.headers);
+	const querystring = parseQueryStringSingular(snapshot.rawUrl);
+	const sourceIp = snapshot.sourceIp ?? "127.0.0.1";
+	const userAgent = headers["user-agent"] ?? "";
+	const req = {
+		method: snapshot.method.toUpperCase(),
+		matchedPath: matchCtx.matchedPath,
+		pathParameters: matchCtx.pathParameters,
+		querystring,
+		headers,
+		body: snapshot.body,
+		sourceIp,
+		userAgent,
+		stage: matchCtx.route.stage,
+		resourcePath: matchCtx.route.pathPattern,
+		requestId: randomUUID()
+	};
+	const deps = {
+		pool: state.pool,
+		rieTimeoutMs: opts.rieTimeoutMs
+	};
+	switch (integration.kind) {
+		case "mock": return dispatchMockIntegration(integration, req);
+		case "http-proxy": return await dispatchHttpProxyIntegration(integration, req, deps);
+		case "http": return await dispatchHttpIntegration(integration, req, deps);
+		case "aws-lambda": return await dispatchAwsLambdaIntegration(integration, req, deps);
+	}
+}
+/**
+* Write a {@link RestV1IntegrationOutcome} to the HTTP response.
+*/
+function writeIntegrationOutcome(res, outcome) {
+	res.statusCode = outcome.statusCode;
+	for (const [name, value] of Object.entries(outcome.headers)) res.setHeader(name, value);
+	res.end(outcome.body);
+}
+/**
 * Attempt CORS preflight interception. Returns `true` when the
 * preflight response was written (caller must NOT continue to route
 * dispatch); `false` when no preflight match (caller falls through to
@@ -45074,7 +46713,7 @@ async function localStartApiCommand(target, options) {
 	await ensureDockerAvailable();
 	const appCmd = resolveApp(options.app);
 	if (!appCmd) throw new Error("No CDK app specified. Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
-	const overrides = readEnvOverridesFile$2(options.envVars);
+	const overrides = readEnvOverridesFile$3(options.envVars);
 	const debugPortBase = options.debugPortBase ? parseDebugPort(options.debugPortBase) : void 0;
 	const perLambdaConcurrency = parsePerLambdaConcurrency(options.perLambdaConcurrency);
 	const inlineTmpDirs = /* @__PURE__ */ new Set();
@@ -45264,7 +46903,9 @@ async function localStartApiCommand(target, options) {
 		if (basePort !== 0) nextPort += 1;
 	}
 	printPerServerRouteTables(servers);
-	warnUnsupportedRoutes(servers.flatMap((s) => s.group.routes.map((r) => r.route)), logger);
+	const allRoutes = servers.flatMap((s) => s.group.routes.map((r) => r.route));
+	warnUnsupportedRoutes(allRoutes, logger);
+	warnSsrfRiskyIntegrations(allRoutes, logger);
 	logger.info(`Per-Lambda concurrency: ${perLambdaConcurrency} (override with --per-lambda-concurrency)`);
 	for (const { group, server } of servers) process.stdout.write(`Server listening on ${server.scheme}://${server.host}:${server.port}  (${group.displayName})\n`);
 	process.stdout.write("^C to stop and clean up containers.\n");
@@ -45813,12 +47454,26 @@ function printRouteTable(routes) {
 	process.stdout.write("Discovered routes:\n");
 	for (const r of sorted) {
 		const sourceLabel = r.source === "http-api" ? "HTTP API" : r.source === "rest-v1" ? `REST v1, stage '${r.stage}'` : "Function URL";
-		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.serviceIntegration ? `[${r.serviceIntegration.subtype}]` : r.lambdaLogicalId;
+		const target = r.mockCors ? "[MOCK CORS preflight]" : r.unsupported ? "[501 Not Implemented]" : r.serviceIntegration ? `[${r.serviceIntegration.subtype}]` : r.restV1Integration ? formatRestV1IntegrationLabel(r.restV1Integration) : r.lambdaLogicalId;
 		process.stdout.write(`  ${r.method.padEnd(methodWidth)}  ${r.pathPattern.padEnd(pathWidth)}  -> ${target}  (${sourceLabel})\n`);
 	}
 	process.stdout.write("\n");
 }
 /**
+* Format the route-table label for a REST v1 non-AWS_PROXY integration.
+* `MOCK` / `HTTP` / `HTTP_PROXY` show their integration kind directly;
+* `AWS` (Lambda non-proxy) shows the Lambda logical id with an `[AWS]`
+* suffix so it's distinguishable from AWS_PROXY rows. Closes #457.
+*/
+function formatRestV1IntegrationLabel(integration) {
+	switch (integration.kind) {
+		case "mock": return "[MOCK]";
+		case "http-proxy": return `[HTTP_PROXY ${integration.uri}]`;
+		case "http": return `[HTTP ${integration.uri}]`;
+		case "aws-lambda": return `${integration.lambdaLogicalId} [AWS]`;
+	}
+}
+/**
 * Materialize an inline Lambda body (`Code.ZipFile`) to a tmpdir and
 * return the directory the container should mount at /var/task.
 * Mirrors `cdkd local invoke`'s implementation; the only divergence is
@@ -45847,7 +47502,7 @@ function getTemplateEnv$1(resource) {
 	return vars;
 }
 /** Read the SAM-shape `--env-vars` JSON file. */
-function readEnvOverridesFile$2(filePath) {
+function readEnvOverridesFile$3(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -45972,6 +47627,26 @@ function warnUnsupportedRoutes(routes, logger) {
 	return unsupported.length;
 }
 /**
+* Surface a one-line warn per HTTP / HTTP_PROXY integration whose
+* `Integration.Uri` points at a well-known internal address space
+* (AWS IMDS, loopback, link-local, RFC1918). PR #505 / issue #457
+* follow-up: cdkd does NOT block these — warn-and-proceed matches the
+* cognito JWKS pass-through pattern — but the user should see the
+* destination at boot so a malicious / typo'd template Uri does not
+* silently exfiltrate credentials in CI. Deduplicated per-Uri.
+*/
+function warnSsrfRiskyIntegrations(routes, logger) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const r of routes) {
+		const integ = r.restV1Integration;
+		if (!integ) continue;
+		if (integ.kind !== "http" && integ.kind !== "http-proxy") continue;
+		if (seen.has(integ.uri)) continue;
+		seen.add(integ.uri);
+		warnSsrfRiskyUri(integ.uri, `${r.method} ${r.pathPattern}`, (msg) => logger.warn(msg));
+	}
+}
+/**
 * One reload cycle for the multi-server topology (issue #260). The
 * watcher serializes calls via a chain promise; this function:
 *
@@ -46020,7 +47695,9 @@ async function reloadAllServers(args) {
 	lastAssetPaths.value = computeAssetPaths(material.specs);
 	if (watcher) watcher.update([output, ...lastAssetPaths.value]);
 	printPerServerRouteTables(servers);
-	warnUnsupportedRoutes(servers.flatMap((s) => s.group.routes.map((r) => r.route)), logger);
+	const allRoutes = servers.flatMap((s) => s.group.routes.map((r) => r.route));
+	warnUnsupportedRoutes(allRoutes, logger);
+	warnSsrfRiskyIntegrations(allRoutes, logger);
 }
 /**
 * Returns true when any value in the function's template env map is a
@@ -46196,14 +47873,38 @@ const execFileAsync$1 = promisify(execFile);
 /** AWS-published sidecar image (latest tag). amd64 is the only image AWS ships. */
 const METADATA_ENDPOINT_IMAGE = "amazon/amazon-ecs-local-container-endpoints:latest-amd64";
 /**
-* Well-known IP for the ECS local-container-endpoints sidecar — matches
-* the documented AWS task-metadata endpoint address. Containers inject
-* `ECS_CONTAINER_METADATA_URI_V4=http://169.254.170.2/v4/<container-id>`
-* to reach it.
+* Default well-known IP for the ECS local-container-endpoints sidecar —
+* matches the documented AWS task-metadata endpoint address. Containers
+* inject `ECS_CONTAINER_METADATA_URI_V4=http://169.254.170.2/v4/<id>`
+* to reach it. `cdkd local run-task` keeps this verbatim; `cdkd local
+* start-service` allocates a per-replica subnet (via `subnetOctet`) so
+* concurrent replicas don't collide on a single docker network range.
 */
 const METADATA_ENDPOINT_IP = "169.254.170.2";
-/** Subnet handed to `docker network create` so the well-known IP is routable. */
-const METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
+/** Default subnet — used when no `subnetOctet` override is supplied. */
+const DEFAULT_METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
+/**
+* Pure-functional subnet allocator. `cdkd local run-task` uses the
+* default subnet; `cdkd local start-service` walks `subnetOctet=170,
+* 171, 172, ...` (one per replica) to keep parallel docker networks
+* from clashing. The link-local 169.254.0.0/16 space is reserved AWS-
+* wide for cloud metadata so collisions with user workloads are
+* unlikely, but each replica still gets its own /24 to ensure
+* docker's `--subnet` allocator does not reject "Pool overlaps".
+*
+* `subnetOctet` is the second-from-last byte of the network: 170 →
+* 169.254.170.0/24 (default), 171 → 169.254.171.0/24, etc. Valid
+* range is 1..254; the runner clamps to `(170 + replicaIndex) % 84`
+* + 170 in practice (rolling window) — exported here so the runner
+* keeps the allocation logic in one place.
+*/
+function buildEndpointSubnet(subnetOctet) {
+	if (subnetOctet < 1 || subnetOctet > 254 || !Number.isInteger(subnetOctet)) throw new Error(`buildEndpointSubnet: subnetOctet must be an integer in 1..254 (got ${subnetOctet}).`);
+	return {
+		cidr: `169.254.${subnetOctet}.0/24`,
+		sidecarIp: `169.254.${subnetOctet}.2`
+	};
+}
 /**
 * Create the per-task docker network + start the metadata-endpoints
 * sidecar. The sidecar must come up at the well-known address BEFORE any
@@ -46213,8 +47914,13 @@ const METADATA_ENDPOINT_SUBNET = "169.254.170.0/24";
 async function createTaskNetwork(options = {}) {
 	const logger = getLogger().child("ecs-network");
 	const networkName = `${options.prefix ?? "cdkd-local"}-task-${randomBytes(4).toString("hex")}`;
+	const subnetOctet = options.subnetOctet ?? 170;
+	const { cidr, sidecarIp } = options.subnetOctet === void 0 ? {
+		cidr: DEFAULT_METADATA_ENDPOINT_SUBNET,
+		sidecarIp: METADATA_ENDPOINT_IP
+	} : buildEndpointSubnet(subnetOctet);
 	await pullImage(METADATA_ENDPOINT_IMAGE, options.skipPull ?? false);
-	logger.info(`Creating docker network ${networkName} (subnet ${METADATA_ENDPOINT_SUBNET})...`);
+	logger.info(`Creating docker network ${networkName} (subnet ${cidr})...`);
 	try {
 		await execFileAsync$1(getDockerCmd(), [
 			"network",
@@ -46222,12 +47928,12 @@ async function createTaskNetwork(options = {}) {
 			"--driver",
 			"bridge",
 			"--subnet",
-			METADATA_ENDPOINT_SUBNET,
+			cidr,
 			networkName
 		]);
 	} catch (err) {
 		const e = err;
-		throw new DockerRunnerError(`docker network create failed: ${e.stderr?.trim() || e.message || String(err)}. Hint: another cdkd run-task on the same host may already own subnet ${METADATA_ENDPOINT_SUBNET}; wait for it to finish, or remove the leftover network with \`docker network ls\` + \`docker network rm\`.`);
+		throw new DockerRunnerError(`docker network create failed: ${e.stderr?.trim() || e.message || String(err)}. Hint: another cdkd run-task on the same host may already own subnet ${cidr}; wait for it to finish, or remove the leftover network with \`docker network ls\` + \`docker network rm\`. \`cdkd local start-service\` walks subnetOctet per replica to avoid this; bare \`cdkd local run-task\` uses the default subnet so only one run can be active at a time.`);
 	}
 	const sidecarArgs = [
 		"run",
@@ -46238,7 +47944,7 @@ async function createTaskNetwork(options = {}) {
 		"--network",
 		networkName,
 		"--ip",
-		METADATA_ENDPOINT_IP
+		sidecarIp
 	];
 	const sidecarEnv = {};
 	if (options.credentials) {
@@ -46249,7 +47955,7 @@ async function createTaskNetwork(options = {}) {
 	if (options.cluster) sidecarEnv["CLUSTER"] = options.cluster;
 	for (const [k, v] of Object.entries(sidecarEnv)) sidecarArgs.push("-e", `${k}=${v}`);
 	sidecarArgs.push(METADATA_ENDPOINT_IMAGE);
-	logger.info("Starting ECS local-container-endpoints sidecar at 169.254.170.2...");
+	logger.info(`Starting ECS local-container-endpoints sidecar at ${sidecarIp}...`);
 	let sidecarContainerId;
 	try {
 		const { stdout } = await execFileAsync$1(getDockerCmd(), sidecarArgs, { maxBuffer: 10 * 1024 * 1024 });
@@ -46261,7 +47967,8 @@ async function createTaskNetwork(options = {}) {
 	}
 	return {
 		networkName,
-		sidecarContainerId
+		sidecarContainerId,
+		sidecarIp
 	};
 }
 /**
@@ -46276,9 +47983,10 @@ async function createTaskNetwork(options = {}) {
 * to whichever credentials AWS SDK chains find).
 */
 function buildMetadataEnv(opts) {
+	const ip = opts.sidecarIp ?? "169.254.170.2";
 	const env = {
-		ECS_CONTAINER_METADATA_URI_V4: `http://${METADATA_ENDPOINT_IP}/v4/${opts.containerName}`,
-		ECS_CONTAINER_METADATA_URI: `http://${METADATA_ENDPOINT_IP}/v3/${opts.containerName}`
+		ECS_CONTAINER_METADATA_URI_V4: `http://${ip}/v4/${opts.containerName}`,
+		ECS_CONTAINER_METADATA_URI: `http://${ip}/v3/${opts.containerName}`
 	};
 	if (opts.roleArn) env["AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"] = `/role/${encodeURIComponent(opts.roleArn)}`;
 	if (opts.region) env["AWS_REGION"] = opts.region;
@@ -46527,6 +48235,7 @@ async function runEcsTask(task, options, state) {
 	};
 	if (options.taskCredentials) netCreateOpts.credentials = options.taskCredentials;
 	if (options.cluster) netCreateOpts.cluster = options.cluster;
+	if (options.subnetOctet !== void 0) netCreateOpts.subnetOctet = options.subnetOctet;
 	state.network = await createTaskNetwork(netCreateOpts);
 	const volumeByName = await realizeDockerVolumes(task.volumes, state);
 	const dockerCmds = /* @__PURE__ */ new Map();
@@ -46544,7 +48253,8 @@ async function runEcsTask(task, options, state) {
 			containerHost: options.containerHost,
 			roleArn: options.taskRoleArn,
 			platformOverride: options.platformOverride,
-			region: options.region
+			region: options.region,
+			sidecarIp: state.network.sidecarIp
 		}));
 	}
 	const startedByName = /* @__PURE__ */ new Map();
@@ -46681,7 +48391,7 @@ async function waitForContainerHealthy(containerId, displayName) {
 			if (err instanceof EcsTaskRunnerError) throw err;
 			logger.debug(`docker inspect on '${displayName}' failed: ${err instanceof Error ? err.message : String(err)}`);
 		}
-		await sleep(1e3);
+		await sleep$1(1e3);
 	}
 	throw new EcsTaskRunnerError(`Container '${displayName}' did not become healthy within 5 minutes.`);
 }
@@ -46705,7 +48415,7 @@ async function stopContainer(containerId, graceSeconds) {
 		]);
 	} catch {}
 }
-function sleep(ms) {
+function sleep$1(ms) {
 	return new Promise((res) => setTimeout(res, ms));
 }
 /**
@@ -46885,7 +48595,8 @@ function buildDockerRunArgs(opts) {
 	const metaEnv = buildMetadataEnv({
 		containerName: container.name,
 		...roleArn !== void 0 && { roleArn },
-		...opts.region !== void 0 && { region: opts.region }
+		...opts.region !== void 0 && { region: opts.region },
+		...opts.sidecarIp !== void 0 && { sidecarIp: opts.sidecarIp }
 	});
 	Object.assign(finalEnv, metaEnv);
 	Object.assign(finalEnv, container.environment);
@@ -46986,7 +48697,7 @@ async function localRunTaskCommand(target, options) {
 			...Object.keys(context).length > 0 && { context }
 		};
 		const { stacks } = await synthesizer.synthesize(synthOpts);
-		const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
+		const imageContext = await buildEcsImageResolutionContext$1(target, stacks, options);
 		const task = resolveEcsTaskTarget(target, stacks, imageContext);
 		logger.info(`Target: ${task.stack.stackName}/${task.taskDefinitionLogicalId} (family=${task.family}, containers=${task.containers.length})`);
 		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === task.stack.stackName) ?? task.stack);
@@ -47028,13 +48739,13 @@ async function localRunTaskCommand(target, options) {
 		let resolvedRoleArn;
 		if (options.assumeTaskRole === true) {
 			if (!task.taskRoleArn) throw new Error("--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Either the task definition does not set TaskRoleArn, or it points at a resource cdkd cannot resolve to an IAM Role at synth time. Pass the ARN explicitly: --assume-task-role <arn>");
-			resolvedRoleArn = await resolvePlaceholderAccount(task.taskRoleArn, options.region);
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+			resolvedRoleArn = await resolvePlaceholderAccount$1(task.taskRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
 		} else if (typeof options.assumeTaskRole === "string") {
 			resolvedRoleArn = options.assumeTaskRole;
-			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole$1(resolvedRoleArn, options.region);
 		}
-		const envOverrides = readEnvOverridesFile$1(options.envVars);
+		const envOverrides = readEnvOverridesFile$2(options.envVars);
 		const runOpts = {
 			cluster: options.cluster,
 			containerHost: options.containerHost,
@@ -47069,7 +48780,7 @@ async function localRunTaskCommand(target, options) {
 * Lazy: callers should only invoke this when the resolved ARN is actually
 * going to be used (i.e. on the bare `--assume-task-role` path).
 */
-async function resolvePlaceholderAccount(arn, region) {
+async function resolvePlaceholderAccount$1(arn, region) {
 	if (!arn.includes("${AWS::AccountId}")) return arn;
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
@@ -47085,7 +48796,7 @@ async function resolvePlaceholderAccount(arn, region) {
 * Assume `roleArn` and return temp credentials. Mirrors the same flow
 * `cdkd local invoke --assume-role` uses.
 */
-async function assumeTaskRole(roleArn, region) {
+async function assumeTaskRole$1(roleArn, region) {
 	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -47116,9 +48827,9 @@ async function assumeTaskRole(roleArn, region) {
 * for the candidate stack — same warn-and-fall-back error policy as
 * `cdkd local invoke --from-state`.
 */
-async function buildEcsImageResolutionContext(target, stacks, options) {
+async function buildEcsImageResolutionContext$1(target, stacks, options) {
 	const logger = getLogger();
-	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	const candidate = pickCandidateStack$1(parseEcsTarget(target).stackPattern, stacks);
 	if (!candidate) return void 0;
 	const needs = detectEcsImageResolutionNeeds(candidate);
 	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
@@ -47129,7 +48840,7 @@ async function buildEcsImageResolutionContext(target, stacks, options) {
 		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
 		let accountId;
 		try {
-			accountId = await resolveCallerAccountId(region);
+			accountId = await resolveCallerAccountId$1(region);
 		} catch (err) {
 			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
 		}
@@ -47157,7 +48868,7 @@ async function buildEcsImageResolutionContext(target, stacks, options) {
 	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics (Ref / Fn::GetAtt / Fn::Sub / Fn::Join). Pass --from-state to substitute them against the deployed cdkd state. Without --from-state these entries are dropped (per-key warnings will follow).");
 	return ctx;
 }
-function pickCandidateStack(stackPattern, stacks) {
+function pickCandidateStack$1(stackPattern, stacks) {
 	if (stackPattern === null) {
 		if (stacks.length === 1) return stacks[0];
 		return;
@@ -47165,7 +48876,7 @@ function pickCandidateStack(stackPattern, stacks) {
 	const matched = matchStacks(stacks, [stackPattern]);
 	if (matched.length === 1) return matched[0];
 }
-async function resolveCallerAccountId(region) {
+async function resolveCallerAccountId$1(region) {
 	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
 	const sts = new STSClient({ ...region && { region } });
 	try {
@@ -47179,7 +48890,7 @@ async function resolveCallerAccountId(region) {
 * `cdkd local invoke --env-vars`: top-level keys are container names, with
 * `Parameters` reserved for global entries.
 */
-function readEnvOverridesFile$1(filePath) {
+function readEnvOverridesFile$2(filePath) {
 	if (!filePath) return void 0;
 	let raw;
 	try {
@@ -47208,6 +48919,690 @@ function createLocalRunTaskCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/local/ecs-service-resolver.ts
+/**
+* Walk the synth template to locate an `AWS::ECS::Service` by display
+* path or stack-qualified logical id, resolve its `TaskDefinition`
+* reference, and chain into the existing `resolveEcsTaskTarget` machinery
+* to produce a `ResolvedEcsService` carrying both the service knobs and
+* the underlying task descriptor.
+*
+* Target shape mirrors `cdkd local run-task`: `<Stack>/<DisplayPath>` or
+* `<Stack>:<LogicalId>`; single-stack apps may omit the stack prefix.
+*
+* Optional `context` (same as the task resolver) carries the ECR image
+* substitution data — pseudo parameters (Tier 1) + state-recorded
+* resources (Tier 2). The CLI builds it lazily when the candidate
+* service's task definition actually needs substitution.
+*/
+function resolveEcsServiceTarget(target, stacks, context) {
+	if (stacks.length === 0) throw new EcsTaskResolutionError("No stacks found in the synthesized assembly.");
+	const parsed = parseEcsTarget(target);
+	const stack = pickStack(parsed, stacks);
+	const resources = stack.template.Resources ?? {};
+	let serviceLogicalId;
+	let serviceResource;
+	if (parsed.isPath) {
+		const index = buildCdkPathIndex(stack.template);
+		const services = resolveCdkPathToLogicalIds(parsed.pathOrId, index).filter(({ logicalId: l }) => resources[l]?.Type === "AWS::ECS::Service");
+		if (services.length === 0) throw notFoundError(target, stack, resources);
+		if (services.length > 1) throw new EcsTaskResolutionError(`Target '${target}' matches ${services.length} ECS services in ${stack.stackName}: ` + services.map((s) => s.logicalId).join(", ") + ". Refine the path or use the stack:LogicalId form.");
+		serviceLogicalId = services[0].logicalId;
+		serviceResource = resources[serviceLogicalId];
+	} else {
+		serviceResource = resources[parsed.pathOrId];
+		if (!serviceResource) throw notFoundError(target, stack, resources);
+		serviceLogicalId = parsed.pathOrId;
+	}
+	if (!serviceLogicalId || !serviceResource) throw notFoundError(target, stack, resources);
+	if (serviceResource.Type === "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is an ECS TaskDefinition, not a Service. Use \`cdkd local run-task\` for one-shot tasks; \`cdkd local start-service\` is Service-only.`);
+	if (serviceResource.Type !== "AWS::ECS::Service") throw new EcsTaskResolutionError(`Resource '${serviceLogicalId}' in ${stack.stackName} is ${serviceResource.Type}, not an AWS::ECS::Service.`);
+	return extractServiceProperties(stack, serviceLogicalId, serviceResource, stacks, context);
+}
+/**
+* Pure-functional extraction from the synth resource. Exposed for unit
+* testing the per-field resolution rules (DesiredCount default, missing
+* TaskDefinition, intrinsic shapes).
+*/
+function extractServiceProperties(stack, serviceLogicalId, resource, stacks, context) {
+	const props = resource.Properties ?? {};
+	const warnings = [];
+	const taskDefRef = props["TaskDefinition"];
+	if (taskDefRef === void 0 || taskDefRef === null) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' in ${stack.stackName} has no TaskDefinition property.`);
+	const taskDefLogicalId = resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId);
+	const task = resolveEcsTaskTarget(`${stack.stackName}:${taskDefLogicalId}`, stacks, context);
+	const desiredCount = parseDesiredCount(props["DesiredCount"], serviceLogicalId);
+	const healthCheckGracePeriodSeconds = parseHealthCheckGrace(props["HealthCheckGracePeriodSeconds"], serviceLogicalId);
+	const serviceName = parseServiceName(props["ServiceName"], serviceLogicalId);
+	if (Array.isArray(props["LoadBalancers"]) && props["LoadBalancers"].length > 0) warnings.push(`ECS Service '${serviceLogicalId}' declares LoadBalancers, but local load-balancer emulation is deferred to a follow-up PR. Containers are NOT registered to a local listener; reach them via their published ports.`);
+	if (props["ServiceConnectConfiguration"]) warnings.push(`ECS Service '${serviceLogicalId}' declares ServiceConnectConfiguration, but Service Connect / Cloud Map emulation is deferred (tracked in #460). Cross-service discovery between locally-run services is not provided.`);
+	return {
+		stack,
+		serviceLogicalId,
+		resource,
+		serviceName,
+		desiredCount,
+		healthCheckGracePeriodSeconds,
+		task,
+		warnings
+	};
+}
+/**
+* Resolve `Properties.TaskDefinition` to a logical id in the same stack.
+* Accepted shapes — verified against real CDK 2.x `cdk synth` output on
+* 2026-05-22 (per `feedback_verify_cdk_synth_shape_before_resolver.md`):
+*   - `{Ref: '<TaskDefLogicalId>'}` — the CDK-canonical shape emitted by
+*     `new ecs.FargateService({ taskDefinition })`.
+*   - flat string `'<TaskDefLogicalId>'` — accepted defensively but CDK
+*     rarely emits this for cross-resource refs.
+* Other intrinsic shapes (`Fn::ImportValue` / `Fn::GetAtt` / etc.) are
+* rejected — cross-stack task definitions and `Fn::GetAtt` shapes have
+* no clean local resolution and would land here only as user errors.
+*/
+function resolveTaskDefinitionReference(taskDefRef, stack, serviceLogicalId) {
+	if (typeof taskDefRef === "string") return taskDefRef;
+	if (taskDefRef && typeof taskDefRef === "object" && !Array.isArray(taskDefRef)) {
+		const refValue = taskDefRef["Ref"];
+		if (typeof refValue === "string") {
+			const target = (stack.template.Resources ?? {})[refValue];
+			if (!target) throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' references TaskDefinition '${refValue}' but no such resource exists in ${stack.stackName}.`);
+			if (target.Type !== "AWS::ECS::TaskDefinition") throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' references '${refValue}' as TaskDefinition but it is of type ${target.Type}, not AWS::ECS::TaskDefinition.`);
+			return refValue;
+		}
+	}
+	throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' has an unsupported TaskDefinition reference shape: ${JSON.stringify(taskDefRef)}. cdkd local start-service v1 supports only Ref to a same-stack AWS::ECS::TaskDefinition; cross-stack TaskDefinitions are deferred.`);
+}
+function parseDesiredCount(raw, serviceLogicalId) {
+	if (raw === void 0 || raw === null) return 1;
+	if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+	if (typeof raw === "string" && /^\d+$/.test(raw)) return parseInt(raw, 10);
+	throw new EcsTaskResolutionError(`ECS Service '${serviceLogicalId}' has an unsupported DesiredCount value: ${JSON.stringify(raw)}. Must be a non-negative integer.`);
+}
+function parseHealthCheckGrace(raw, _serviceLogicalId) {
+	if (raw === void 0 || raw === null) return 30;
+	if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return Math.floor(raw);
+	if (typeof raw === "string" && /^\d+$/.test(raw)) return parseInt(raw, 10);
+	return 30;
+}
+function parseServiceName(raw, serviceLogicalId) {
+	if (typeof raw === "string" && raw.length > 0) return raw;
+	return serviceLogicalId;
+}
+/**
+* Local copy of the same `pickStack` helper used by the task resolver.
+* Kept in-file rather than exported from `ecs-task-resolver.ts` so future
+* service-specific extensions (e.g. cross-stack service-to-task refs)
+* can diverge without breaking the run-task code path.
+*/
+function pickStack(parsed, stacks) {
+	if (parsed.stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		throw new EcsTaskResolutionError(`Target has no stack prefix, and the assembly contains ${stacks.length} stacks: ${stacks.map((s) => s.stackName).join(", ")}. Pass the target as 'Stack/Path' or 'Stack:LogicalId'.`);
+	}
+	const matched = matchStacks(stacks, [parsed.stackPattern]);
+	if (matched.length === 0) throw new EcsTaskResolutionError(`No stack matches '${parsed.stackPattern}'. Available stacks: ${stacks.map((s) => s.stackName).join(", ")}.`);
+	if (matched.length > 1) throw new EcsTaskResolutionError(`Multiple stacks match '${parsed.stackPattern}': ${matched.map((s) => s.stackName).join(", ")}. Refine the pattern.`);
+	return matched[0];
+}
+function notFoundError(target, stack, resources) {
+	const services = Object.entries(resources).filter(([, r]) => r.Type === "AWS::ECS::Service").map(([id]) => id);
+	if (services.length === 0) return new EcsTaskResolutionError(`Target '${target}' did not match any resource in ${stack.stackName}, and the stack declares no AWS::ECS::Service resources at all.`);
+	return new EcsTaskResolutionError(`Target '${target}' did not match any ECS Service in ${stack.stackName}. Available services: ${services.join(", ")}.`);
+}
+
+//#endregion
+//#region src/local/ecs-service-runner.ts
+/**
+* Phase 2 of #262 — long-running ECS Service emulator. Wraps the existing
+* `ecs-task-runner` machinery in a replica pool: N concurrent task
+* instances per `DesiredCount`, each with its own docker network +
+* metadata sidecar + container set. Tasks that exit non-zero AFTER the
+* health-check grace period are restarted with exponential backoff so a
+* crash-looping container does not hammer docker.
+*
+* v1 scope (per the issue's PR-split recommendation):
+*   - Replica pool sizing via `DesiredCount` clamped by `--max-tasks`.
+*   - Restart-on-exit with exponential backoff (1s → 30s, capped) +
+*     a per-instance retry counter so a permanently-broken container
+*     stops compounding cleanup work.
+*   - Long-running lifecycle (returns only on shutdown).
+*
+* Deferred to follow-up PRs:
+*   - Local load-balancer emulation (LB listener + target-group health
+*     check + round-robin) — separate PR per the issue's PR-split.
+*   - Service Connect / Cloud Map (tracked in #460).
+*   - Rolling deployment (`--reload` / `--watch`).
+*/
+var EcsServiceRunnerError = class EcsServiceRunnerError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "EcsServiceRunnerError";
+		Object.setPrototypeOf(this, EcsServiceRunnerError.prototype);
+	}
+};
+function createServiceRunState() {
+	return {
+		replicas: [],
+		shuttingDown: false
+	};
+}
+/**
+* Compute the effective replica count for a service: the smaller of
+* `service.desiredCount` and `--max-tasks`, floored at 1. Pure-
+* functional so the CLI can show the user what cdkd is about to do
+* before any docker calls fire.
+*/
+function computeReplicaCount(desiredCount, maxTasks) {
+	if (maxTasks < 1) throw new EcsServiceRunnerError(`--max-tasks must be >= 1 (got ${maxTasks}); local dev needs at least one running replica.`);
+	if (desiredCount <= 0) return 1;
+	return Math.min(desiredCount, maxTasks);
+}
+/**
+* Exponential backoff schedule: 1s, 2s, 4s, 8s, 16s, 30s, 30s, ... Used
+* between restarts of a crash-looping replica so docker is not hammered
+* by the watcher loop. Exposed for unit testing.
+*/
+function backoffDelayMs(restartCount) {
+	return Math.min(1e3 * Math.pow(2, Math.min(restartCount, 10)), 3e4);
+}
+/**
+* Decide whether a replica that just exited should restart. Pure-
+* functional so the watcher loop's policy is easy to unit-test.
+*/
+function shouldRestart(exitCode, policy) {
+	if (policy === "none") return false;
+	if (policy === "always") return true;
+	return exitCode !== 0;
+}
+/**
+* Long-running entry point. Boots `replicaCount` instances of the
+* service's task descriptor, returns a controller object the CLI uses
+* to (1) wait for the first failure that gives up restarting and (2)
+* shut every replica down on SIGINT / SIGTERM.
+*
+* The returned `shutdown()` is idempotent and safe to call from
+* multiple SIGINT handlers (CLI's single-flight pattern wraps it
+* anyway).
+*/
+async function startEcsService(service, options, runState) {
+	const logger = getLogger().child("ecs-service");
+	for (const w of service.warnings) logger.warn(w);
+	const replicaCount = computeReplicaCount(service.desiredCount, options.maxTasks);
+	if (replicaCount < service.desiredCount) logger.warn(`Service '${service.serviceName}' template DesiredCount=${service.desiredCount} exceeds --max-tasks=${options.maxTasks}; running ${replicaCount} replica(s) locally. Raise --max-tasks to lift the cap, or accept the reduced concurrency for local dev.`);
+	logger.info(`Starting ECS service '${service.serviceName}' with ${replicaCount} replica(s) (restartPolicy=${options.restartPolicy})`);
+	for (let i = 0; i < replicaCount; i++) {
+		const instance = {
+			index: i,
+			state: createEcsRunState(),
+			restartCount: 0,
+			shuttingDown: false,
+			inFlightBoot: void 0
+		};
+		runState.replicas.push(instance);
+		const bootPromise = bootReplica(service, options, instance);
+		instance.inFlightBoot = bootPromise;
+		try {
+			await bootPromise;
+		} catch (err) {
+			instance.lastError = err instanceof Error ? err : new Error(String(err));
+			throw new EcsServiceRunnerError(`Failed to boot replica ${i} of service '${service.serviceName}': ${instance.lastError.message}`);
+		} finally {
+			instance.inFlightBoot = void 0;
+		}
+	}
+	for (const instance of runState.replicas) watchReplica(service, options, instance, runState);
+	return new ServiceController(service, runState, options);
+}
+/**
+* Public controller surface. The CLI awaits `controller.waitForShutdown()`
+* to block until the user ^Cs. `controller.shutdown()` is wired into the
+* SIGINT / SIGTERM handlers.
+*/
+var ServiceController = class {
+	service;
+	runState;
+	options;
+	shutdownResolve;
+	shutdownPromise;
+	/**
+	* Single-flight wrapper for `shutdown()` so the fan-out cleanup runs
+	* exactly once even when SIGINT and the CLI's outer `finally` both
+	* fire (the canonical pattern documented in
+	* `feedback_sigint_finally_cleanup_singleflight.md`). Built in the
+	* constructor so every call to `shutdown()` resolves against the same
+	* underlying promise.
+	*/
+	runShutdown;
+	constructor(service, runState, options) {
+		this.service = service;
+		this.runState = runState;
+		this.options = options;
+		this.shutdownPromise = new Promise((resolve) => {
+			this.shutdownResolve = resolve;
+		});
+		this.runShutdown = singleFlight(() => this.doShutdown());
+	}
+	/**
+	* Returns the count of currently-active (non-shutting-down) replicas.
+	* Exposed so the CLI can surface a one-line "service is degraded"
+	* banner when restarts stop firing.
+	*/
+	activeReplicaCount() {
+		return this.runState.replicas.filter((r) => !r.shuttingDown).length;
+	}
+	/**
+	* Block until `shutdown()` is called. Used by the CLI as the
+	* long-running blocking point — the SIGINT handler resolves it.
+	*/
+	waitForShutdown() {
+		return this.shutdownPromise;
+	}
+	/**
+	* Idempotent fan-out shutdown across every active replica. Wired into
+	* both SIGINT and the outer `finally` of the CLI command; the
+	* `singleFlight`-wrapped `runShutdown` collapses concurrent / repeated
+	* callers to one underlying invocation.
+	*/
+	async shutdown() {
+		await this.runShutdown();
+		return this.shutdownPromise;
+	}
+	async doShutdown() {
+		this.runState.shuttingDown = true;
+		const logger = getLogger().child("ecs-service");
+		logger.info(`Shutting down service '${this.service.serviceName}'...`);
+		for (const r of this.runState.replicas) r.shuttingDown = true;
+		const inFlightBoots = this.runState.replicas.map((r) => r.inFlightBoot).filter((p) => p !== void 0);
+		if (inFlightBoots.length > 0) {
+			logger.debug(`Awaiting ${inFlightBoots.length} in-flight bootReplica() call(s) before cleanup...`);
+			await Promise.allSettled(inFlightBoots);
+		}
+		await Promise.allSettled(this.runState.replicas.map(async (instance) => {
+			try {
+				await cleanupEcsRun(instance.state, { keepRunning: this.options.taskOptions.keepRunning });
+			} catch (err) {
+				logger.debug(`Replica ${instance.index} cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}));
+		this.shutdownResolve?.();
+	}
+};
+/**
+* Boot a single replica. Mutates the supplied `instance.state` so the
+* shutdown path's `cleanupEcsRun(instance.state)` covers every partial
+* side effect. Network names are suffixed with the replica index so
+* docker doesn't collide on shared per-task network names when N > 1.
+*/
+async function bootReplica(service, options, instance) {
+	const logger = getLogger().child("ecs-service");
+	const perReplicaCluster = `${options.taskOptions.cluster}-svc-${service.serviceLogicalId.toLowerCase()}-r${instance.index}`;
+	const perReplicaSubnetOctet = 170 + instance.index % 84;
+	const perReplicaTaskOptions = {
+		...options.taskOptions,
+		cluster: perReplicaCluster,
+		subnetOctet: perReplicaSubnetOctet,
+		detach: true
+	};
+	logger.info(`Booting replica ${instance.index} (${perReplicaCluster})`);
+	await runEcsTask(service.task, perReplicaTaskOptions, instance.state);
+}
+/**
+* Long-running watcher loop for one replica. Polls the essential
+* container's exit code via `docker wait`; on exit, decides whether to
+* restart per `restartPolicy` + applies exponential backoff. The loop
+* exits only when the replica's `shuttingDown` flag is set.
+*/
+async function watchReplica(service, options, instance, runState) {
+	const logger = getLogger().child("ecs-service");
+	while (!instance.shuttingDown && !runState.shuttingDown) {
+		const essentialId = pickEssentialContainerId(instance, service);
+		if (!essentialId) {
+			await sleep(500);
+			continue;
+		}
+		let exitCode;
+		try {
+			exitCode = await waitForExitImpl(essentialId);
+		} catch (err) {
+			logger.debug(`docker wait failed for replica ${instance.index}: ${err instanceof Error ? err.message : String(err)}`);
+			exitCode = -1;
+		}
+		if (instance.shuttingDown || runState.shuttingDown) return;
+		logger.warn(`Replica ${instance.index} essential container exited with code ${exitCode} (restartCount=${instance.restartCount}).`);
+		if (!shouldRestart(exitCode, options.restartPolicy)) {
+			logger.warn(`Replica ${instance.index} not restarting (policy=${options.restartPolicy}, exit=${exitCode}). Service running in degraded mode.`);
+			instance.shuttingDown = true;
+			return;
+		}
+		const delay = backoffDelayMs(instance.restartCount);
+		logger.info(`Restarting replica ${instance.index} in ${delay}ms...`);
+		await sleep(delay);
+		if (instance.shuttingDown || runState.shuttingDown) return;
+		try {
+			await cleanupEcsRun(instance.state, { keepRunning: false });
+		} catch (err) {
+			logger.debug(`Replica ${instance.index} pre-restart cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		instance.state = createEcsRunState();
+		instance.restartCount += 1;
+		const bootPromise = bootReplica(service, options, instance);
+		instance.inFlightBoot = bootPromise;
+		try {
+			await bootPromise;
+		} catch (err) {
+			instance.lastError = err instanceof Error ? err : new Error(String(err));
+			logger.error(`Replica ${instance.index} restart failed: ${instance.lastError.message}. Service running in degraded mode.`);
+			instance.shuttingDown = true;
+			return;
+		} finally {
+			instance.inFlightBoot = void 0;
+		}
+	}
+}
+function pickEssentialContainerId(instance, service) {
+	if (service) {
+		const essential = service.task.containers.find((c) => c.essential) ?? service.task.containers[0];
+		if (essential) {
+			const started = instance.state.startedContainers.find((c) => c.name === essential.name);
+			if (started) return started.id;
+		}
+	}
+	return instance.state.startedContainers[0]?.id;
+}
+/**
+* Production `docker wait <id>` implementation. Captured once so the
+* test override can restore it without duplicating the body.
+*/
+const defaultWaitForExitImpl = async (containerId) => {
+	const { execFile } = await import("node:child_process");
+	const { promisify } = await import("node:util");
+	const { getDockerCmd } = await import("./docker-cmd-EtWSTAje.js").then((n) => n.t);
+	const { stdout } = await promisify(execFile)(getDockerCmd(), ["wait", containerId], { maxBuffer: 1024 * 1024 });
+	const code = parseInt(stdout.trim(), 10);
+	return Number.isFinite(code) ? code : -1;
+};
+/**
+* `docker wait <id>` returns the exit code on stdout. Extracted as a
+* test-overridable function so unit tests do not need a real container.
+*/
+let waitForExitImpl = defaultWaitForExitImpl;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+//#endregion
+//#region src/cli/commands/local-start-service.ts
+/**
+* `cdkd local start-service <Stack/Service>` — Phase 2 of #262. Spins up
+* `DesiredCount` task replicas locally (clamped by `--max-tasks`) using
+* the existing `ecs-task-runner` per replica. Long-running; ^C cleans
+* every replica + sidecar + per-task network.
+*
+* Deferred to follow-up PRs (matches the issue's PR-split):
+*   - Local LB emulator (listener + round-robin + target-group health
+*     check) — PR C of #466.
+*   - Rolling deployment (`--watch` / `--reload`) — PR D of #466.
+*   - Service Connect / Cloud Map — tracked separately in #460.
+*/
+async function localStartServiceCommand(target, options) {
+	const logger = getLogger();
+	if (options.verbose) logger.setLevel("debug");
+	warnIfDeprecatedRegion(options);
+	const runState = createServiceRunState();
+	let sigintHandler;
+	let sigintCount = 0;
+	let controller;
+	const cleanup = singleFlight(async () => {
+		if (controller) await controller.shutdown();
+		else await Promise.allSettled(runState.replicas.map((r) => cleanupEcsRun(r.state, { keepRunning: false }).catch(() => void 0)));
+	}, (err) => getLogger().debug(`service cleanup failed: ${err instanceof Error ? err.message : String(err)}`));
+	try {
+		await applyRoleArnIfSet({
+			roleArn: options.roleArn,
+			region: options.region
+		});
+		await ensureDockerAvailable();
+		const appCmd = resolveApp(options.app);
+		if (!appCmd) throw new Error("No CDK app specified. Pass --app, set CDKD_APP, or add \"app\" to cdk.json.");
+		logger.info("Synthesizing CDK app...");
+		const synthesizer = new Synthesizer();
+		const context = parseContextOptions(options.context);
+		const synthOpts = {
+			app: appCmd,
+			output: options.output,
+			...options.region && { region: options.region },
+			...options.profile && { profile: options.profile },
+			...Object.keys(context).length > 0 && { context }
+		};
+		const { stacks } = await synthesizer.synthesize(synthOpts);
+		const imageContext = await buildEcsImageResolutionContext(target, stacks, options);
+		const service = resolveEcsServiceTarget(target, stacks, imageContext);
+		logger.info(`Target: ${service.stack.stackName}/${service.serviceLogicalId} (service=${service.serviceName}, desiredCount=${service.desiredCount}, task=${service.task.taskDefinitionLogicalId})`);
+		const taskNeeds = detectEcsImageResolutionNeeds(stacks.find((s) => s.stackName === service.stack.stackName) ?? service.stack);
+		if (options.fromState && taskNeeds.needsCrossStackResolver) {
+			const consumerRegion = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? service.stack.region ?? "us-east-1";
+			const built = await buildCrossStackResolver(consumerRegion, {
+				...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
+				statePrefix: options.statePrefix,
+				...options.region !== void 0 && { region: options.region },
+				...options.profile !== void 0 && { profile: options.profile }
+			});
+			if (built) try {
+				const subContext = {
+					resources: imageContext?.stateResources ?? {},
+					...imageContext?.pseudoParameters && { pseudoParameters: imageContext.pseudoParameters },
+					consumerRegion,
+					crossStackResolver: built.resolver
+				};
+				await applyCrossStackResolverToTask(service.task, subContext);
+			} finally {
+				built.dispose();
+			}
+		} else if (!options.fromState && taskNeeds.needsCrossStackResolver) logger.warn("Container Environment / Secrets entries contain Fn::ImportValue / Fn::GetStackOutput intrinsics. Pass --from-state to substitute them against deployed cdkd state.");
+		sigintHandler = () => {
+			sigintCount += 1;
+			if (sigintCount >= 2) {
+				process.stderr.write("Force-exit on second ^C; container cleanup skipped.\n");
+				process.exit(130);
+			}
+			logger.info("Stopping service...");
+			cleanup().then(() => process.exit(130));
+		};
+		process.on("SIGINT", sigintHandler);
+		process.on("SIGTERM", sigintHandler);
+		let assumedCredentials;
+		let resolvedRoleArn;
+		if (options.assumeTaskRole === true) {
+			if (!service.task.taskRoleArn) throw new LocalStartServiceError("--assume-task-role passed without an ARN but the task definition has no resolvable TaskRoleArn. Pass the ARN explicitly: --assume-task-role <arn>");
+			resolvedRoleArn = await resolvePlaceholderAccount(service.task.taskRoleArn, options.region);
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+		} else if (typeof options.assumeTaskRole === "string") {
+			resolvedRoleArn = options.assumeTaskRole;
+			assumedCredentials = await assumeTaskRole(resolvedRoleArn, options.region);
+		}
+		const envOverrides = readEnvOverridesFile$1(options.envVars);
+		const taskOpts = {
+			cluster: options.cluster,
+			containerHost: options.containerHost,
+			skipPull: options.pull === false,
+			keepRunning: false,
+			detach: true
+		};
+		if (envOverrides) taskOpts.envOverrides = envOverrides;
+		if (assumedCredentials) taskOpts.taskCredentials = assumedCredentials;
+		if (resolvedRoleArn) taskOpts.taskRoleArn = resolvedRoleArn;
+		if (options.platform) taskOpts.platformOverride = options.platform;
+		if (options.region) taskOpts.region = options.region;
+		if (options.ecrRoleArn) taskOpts.ecrRoleArn = options.ecrRoleArn;
+		controller = await startEcsService(service, {
+			maxTasks: options.maxTasks,
+			restartPolicy: options.restartPolicy,
+			taskOptions: taskOpts
+		}, runState);
+		logger.info(`Service '${service.serviceName}' running with ${controller.activeReplicaCount()} active replica(s). Press ^C to shut down.`);
+		await controller.waitForShutdown();
+	} finally {
+		if (sigintHandler) {
+			process.off("SIGINT", sigintHandler);
+			process.off("SIGTERM", sigintHandler);
+		}
+		await cleanup();
+	}
+}
+async function resolvePlaceholderAccount(arn, region) {
+	if (!arn.includes("${AWS::AccountId}")) return arn;
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const account = (await sts.send(new GetCallerIdentityCommand({}))).Account;
+		if (!account) throw new LocalStartServiceError(`--assume-task-role: GetCallerIdentity returned no Account; cannot resolve placeholder ARN '${arn}'.`);
+		return arn.split(TASK_ROLE_ACCOUNT_PLACEHOLDER).join(account);
+	} finally {
+		sts.destroy();
+	}
+}
+async function assumeTaskRole(roleArn, region) {
+	const { STSClient, AssumeRoleCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		const creds = (await sts.send(new AssumeRoleCommand({
+			RoleArn: roleArn,
+			RoleSessionName: `cdkd-local-start-service-${Date.now()}`,
+			DurationSeconds: 3600
+		}))).Credentials;
+		if (!creds?.AccessKeyId || !creds.SecretAccessKey || !creds.SessionToken) throw new LocalStartServiceError(`AssumeRole(${roleArn}) returned no usable credentials.`);
+		return {
+			accessKeyId: creds.AccessKeyId,
+			secretAccessKey: creds.SecretAccessKey,
+			sessionToken: creds.SessionToken
+		};
+	} finally {
+		sts.destroy();
+	}
+}
+/**
+* Build the substitution context the ECS resolver consumes. Identical
+* shape to `local-run-task.ts:buildEcsImageResolutionContext` — only
+* the candidate stack picker differs because services and tasks share
+* the same stack-pattern grammar.
+*/
+async function buildEcsImageResolutionContext(target, stacks, options) {
+	const logger = getLogger();
+	const candidate = pickCandidateStack(parseEcsTarget(target).stackPattern, stacks);
+	if (!candidate) return void 0;
+	const needs = detectEcsImageResolutionNeeds(candidate);
+	if (!needs.needsPseudoParameters && !needs.needsStateResources && !needs.needsEnvOrSecretSubstitution) return;
+	const ctx = {};
+	const wantsPseudoForEnvOrSecret = options.fromState && needs.needsEnvOrSecretSubstitution;
+	if (needs.needsPseudoParameters || wantsPseudoForEnvOrSecret) {
+		const region = options.region ?? process.env["AWS_REGION"] ?? process.env["AWS_DEFAULT_REGION"] ?? candidate.region;
+		if (!region) logger.warn("Resolver references ${AWS::Region} but cdkd could not determine the target region. Pass --region, set AWS_REGION, or declare env.region on the CDK stack.");
+		let accountId;
+		try {
+			accountId = await resolveCallerAccountId(region);
+		} catch (err) {
+			logger.warn(`Resolver needs \${AWS::AccountId} but STS GetCallerIdentity failed: ${err instanceof Error ? err.message : String(err)}. Substitution will be skipped; affected env / secret entries will be dropped with per-key warnings.`);
+		}
+		const partitionAndSuffix = region ? derivePartitionAndUrlSuffix(region) : void 0;
+		ctx.pseudoParameters = {
+			...accountId !== void 0 && { accountId },
+			...region !== void 0 && { region },
+			...partitionAndSuffix && {
+				partition: partitionAndSuffix.partition,
+				urlSuffix: partitionAndSuffix.urlSuffix
+			}
+		};
+	}
+	const wantsState = needs.needsStateResources || needs.needsEnvOrSecretSubstitution;
+	if (options.fromState && wantsState) {
+		const loaded = await loadStateForStack(candidate.stackName, candidate.region, {
+			...options.stackRegion !== void 0 && { stackRegion: options.stackRegion },
+			...options.stateBucket !== void 0 && { stateBucket: options.stateBucket },
+			statePrefix: options.statePrefix,
+			...options.region !== void 0 && { region: options.region },
+			...options.profile !== void 0 && { profile: options.profile }
+		});
+		if (loaded) ctx.stateResources = loaded.state.resources;
+	} else if (!options.fromState && needs.needsStateResources) logger.warn("Container Image references a same-stack AWS::ECR::Repository. Pass --from-state to substitute the deployed repository URI.");
+	else if (!options.fromState && needs.needsEnvOrSecretSubstitution) logger.warn("Container Environment / Secrets entries contain CloudFormation intrinsics. Pass --from-state to substitute them against the deployed cdkd state.");
+	return ctx;
+}
+function pickCandidateStack(stackPattern, stacks) {
+	if (stackPattern === null) {
+		if (stacks.length === 1) return stacks[0];
+		return;
+	}
+	const matched = matchStacks(stacks, [stackPattern]);
+	if (matched.length === 1) return matched[0];
+}
+async function resolveCallerAccountId(region) {
+	const { STSClient, GetCallerIdentityCommand } = await import("@aws-sdk/client-sts");
+	const sts = new STSClient({ ...region && { region } });
+	try {
+		return (await sts.send(new GetCallerIdentityCommand({}))).Account;
+	} finally {
+		sts.destroy();
+	}
+}
+function readEnvOverridesFile$1(filePath) {
+	if (!filePath) return void 0;
+	let raw;
+	try {
+		raw = readFileSync(filePath, "utf-8");
+	} catch (err) {
+		throw new LocalStartServiceError(`Failed to read --env-vars file '${filePath}': ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new LocalStartServiceError(`Failed to parse --env-vars file '${filePath}' as JSON: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new LocalStartServiceError(`--env-vars file '${filePath}' must contain a JSON object at the top level.`);
+	return parsed;
+}
+function parsePositiveInt(raw, flagName) {
+	const parsed = parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed < 1) throw new LocalStartServiceError(`${flagName} must be a positive integer (got '${raw}').`);
+	return parsed;
+}
+/**
+* Hard cap on `--max-tasks` driven by the per-replica subnet allocator
+* in `ecs-service-runner.ts:bootReplica` (`170 + (index % 84)`). The
+* `% 84` modulo wraps at index 84, collapsing replica 84's `/24` onto
+* replica 0's allocation. Docker rejects the duplicate-subnet network
+* creation with a cryptic "Pool overlaps with other one on this address
+* space" error 30s into the boot — by which time some early replicas
+* may have spent docker-run budget. Reject at parse time so the user
+* gets an actionable error before any boot work fires.
+*
+* 84 is the count of usable link-local /24 octets in the range
+* `169.254.170.0..169.254.253.0` (255 reserved for broadcast). Raising
+* this requires extending the allocator to walk a different IP range.
+*/
+const MAX_TASKS_SUBNET_RANGE_CAP = 84;
+function parseMaxTasks(raw) {
+	const parsed = parsePositiveInt(raw, "--max-tasks");
+	if (parsed > 84) throw new LocalStartServiceError(`--max-tasks ${parsed} exceeds the per-replica link-local /24 subnet allocator's range (${84}). The allocator in ecs-service-runner.ts assigns each replica its own 169.254.x.0/24 from the range 169.254.170.0..169.254.253.0; replica indices >= ${84} would collide with earlier replicas via modulo wrap. Lower --max-tasks to <= ${84}, or accept reduced local concurrency for high-DesiredCount services.`);
+	return parsed;
+}
+function parseRestartPolicy(raw) {
+	if (raw === "on-failure" || raw === "always" || raw === "none") return raw;
+	throw new LocalStartServiceError(`--restart-policy must be one of 'on-failure', 'always', or 'none' (got '${raw}').`);
+}
+function createLocalStartServiceCommand() {
+	const cmd = new Command("start-service").description("Run an AWS::ECS::Service locally as a long-running emulator. Spins up DesiredCount task replicas (clamped by --max-tasks) using the same per-task docker network + metadata sidecar pattern as `cdkd local run-task`, then keeps each replica running and restarts it on exit per --restart-policy. ^C tears every replica + sidecar + network down. Target accepts a CDK display path (MyStack/MyService) or stack-qualified logical ID (MyStack:MyServiceXYZ); single-stack apps may omit the stack prefix.").argument("<target>", "CDK display path or stack-qualified logical ID of the AWS::ECS::Service to run").addOption(new Option("--cluster <name>", "Cluster name surfaced to ECS_CONTAINER_METADATA_URI_V4 and used as the docker network prefix").default("cdkd-local")).addOption(new Option("--env-vars <file>", "JSON env-var overrides (SAM-compatible: {\"ContainerName\":{\"KEY\":\"VALUE\"}, \"Parameters\":{}})")).addOption(new Option("--container-host <ip>", "Host IP to bind published container ports to. Must be a numeric IP (Docker rejects hostnames here)").default("127.0.0.1")).addOption(new Option("--assume-task-role [arn]", "Assume the task definition's TaskRoleArn (or the supplied ARN) and forward STS-issued temp credentials via the metadata sidecar so containers run with the deployed task role. Bare flag uses the template's TaskRoleArn; pass an explicit ARN to override.")).addOption(new Option("--no-pull", "Skip docker pull for every container image and the metadata sidecar")).addOption(new Option("--ecr-role-arn <arn>", "Role ARN to assume before authenticating against ECR for cross-account / centralized registries.")).addOption(new Option("--platform <platform>", "Force docker --platform (linux/amd64 or linux/arm64). Default: inferred from task RuntimePlatform.CpuArchitecture")).addOption(new Option("--max-tasks <n>", `Hard cap on local replica count. Caps the template DesiredCount so local dev machines don't run an unbounded number of containers. Cannot exceed ${84} due to the per-replica link-local /24 subnet allocator's range.`).default(3).argParser(parseMaxTasks)).addOption(new Option("--restart-policy <policy>", "How to react when an essential container exits. 'on-failure' (default) restarts only on non-zero exit; 'always' restarts on every exit; 'none' shuts the replica down and runs the service degraded.").default("on-failure").argParser(parseRestartPolicy)).addOption(new Option("--from-state", "Read cdkd S3 state for the target stack and substitute Fn::Sub / Fn::GetAtt / Fn::ImportValue / Fn::GetStackOutput intrinsics in container images, environment variables, secrets, role ARNs, and volumes.").default(false)).addOption(new Option("--stack-region <region>", "Region of the cdkd state record to read (used with --from-state when the same stack name has state in multiple regions).")).action(withErrorHandling(localStartServiceCommand));
+	[
+		...commonOptions,
+		...appOptions,
+		...contextOptions,
+		...stateOptions
+	].forEach((opt) => cmd.addOption(opt));
+	cmd.addOption(deprecatedRegionOption);
+	return cmd;
+}
+
 //#endregion
 //#region src/cli/commands/local-invoke.ts
 /**
@@ -47939,6 +50334,7 @@ function createLocalCommand() {
 	local.addCommand(invoke);
 	local.addCommand(createLocalStartApiCommand());
 	local.addCommand(createLocalRunTaskCommand());
+	local.addCommand(createLocalStartServiceCommand());
 	return local;
 }
 
@@ -49311,7 +51707,7 @@ function reorderArgs(argv) {
 */
 async function main() {
 	const program = new Command();
-	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.130.0");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.132.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());