@go-to-k/cdkd 0.97.0 → 0.98.0

package/README.md

@@ -335,6 +335,31 @@ full reference. For per-resource-type provisioning support (SDK Providers
 vs Cloud Control API fallback), see
 **[docs/supported-resources.md](docs/supported-resources.md)**.
 
+### Cross-stack references — strong vs weak
+
+`Fn::ImportValue` is a **strong reference**: `cdkd destroy <producer>`
+refuses to delete a stack while any other stack still imports one of
+its exports via `Fn::ImportValue`. Matches CloudFormation's behavior.
+The error message names every offending consumer and points at the
+two valid resolution paths (destroy the consumer first, or remove
+the `Fn::ImportValue` from the consumer's template and redeploy).
+
+`Fn::GetStackOutput` (cdkd-specific) is a **weak reference**: the
+producer stays deletable independently of consumers. Use it when you
+intentionally want decoupled lifecycles (cross-region / cross-stage /
+staging environments).
+
+A persistent per-region exports index at
+`s3://{state-bucket}/cdkd/_index/{region}/exports.json` makes
+`Fn::ImportValue` resolution O(1) at scale (200-stack environments
+resolve in ~100ms vs minutes with the pre-#343 per-resolve scan).
+The index is a derived view rebuilt from `state.json` on demand —
+state.json remains the canonical source of truth, and strong-reference
+safety checks scan it directly rather than trusting the index.
+
+See **[docs/cross-stack-references.md](docs/cross-stack-references.md)**
+for the full design (schema v4, lifecycle, locking, failure modes).
+
 ## Rollback behavior
 
 When a deploy fails mid-stack (e.g. a resource hits a validation error

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/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 resolveCaptureObservedState, C as stringifyValue, D as getDefaultStateBucketName, E as Synthesizer, F as AssemblyReader, G as ProvisioningError, H as LocalInvokeBuildError, J as RouteDiscoveryError, K as ResourceTimeoutError, L as resolveBucketRegion, M as resolveStateBucketWithDefault, N as resolveStateBucketWithDefaultAndSource, O as getLegacyStateBucketName, P as warnDeprecatedNoPrefixCliFlag, S as AssetPublisher, T as buildDockerImage, W as PartialFailureError, Y as StackTerminationProtectionError, _ as DiffCalculator, a as withRetry, at as runStackBuffered, b as LockManager, c as collectInlinePolicyNamesManagedBySiblings, ct as PATTERN_B_RESOURCE_TYPES, d as normalizeAwsTagsToCfn, dt as withSkipPrefix, et as normalizeAwsError, f as resolveExplicitPhysicalId, ft as withStackName, g as IntrinsicFunctionResolver, h as assertRegionMatch, i as withResourceDeadline, j as resolveSkipPrefix, k as resolveApp, l as CDK_PATH_TAG, lt as generateResourceName, m as CloudControlProvider, n as DEFAULT_RESOURCE_WARN_AFTER_MS, o as IMPLICIT_DELETE_DEPENDENCIES, ot as getLiveRenderer, p as ProviderRegistry, q as ResourceUpdateNotSupportedError, r as DeployEngine, rt as getLogger, s as IAMRoleProvider, st as PATTERN_B_NAME_PROPERTIES, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as withErrorHandling, u as matchesCdkPath, ut as generateResourceNameWithFallback, v as DagBuilder, w as WorkGraph, x as S3StateBackend, y as TemplateParser, z as CdkdError } from "./deploy-engine-Cl7v7Ml5.js";
+import { A as resolveCaptureObservedState, C as stringifyValue, D as getDefaultStateBucketName, E as Synthesizer, F as AssemblyReader, G as ProvisioningError, H as LocalInvokeBuildError, J as RouteDiscoveryError, K as ResourceTimeoutError, L as resolveBucketRegion, M as resolveStateBucketWithDefault, N as resolveStateBucketWithDefaultAndSource, O as getLegacyStateBucketName, P as warnDeprecatedNoPrefixCliFlag, S as AssetPublisher, T as buildDockerImage, W as PartialFailureError, X as StackTerminationProtectionError, Y as StackHasActiveImportsError, _ as DiffCalculator, a as withRetry, b as LockManager, c as collectInlinePolicyNamesManagedBySiblings, ct as PATTERN_B_NAME_PROPERTIES, d as normalizeAwsTagsToCfn, dt as generateResourceNameWithFallback, f as resolveExplicitPhysicalId, ft as withSkipPrefix, g as IntrinsicFunctionResolver, h as assertRegionMatch, i as withResourceDeadline, it as getLogger, j as resolveSkipPrefix, k as resolveApp, l as CDK_PATH_TAG, lt as PATTERN_B_RESOURCE_TYPES, m as CloudControlProvider, n as DEFAULT_RESOURCE_WARN_AFTER_MS, nt as withErrorHandling, o as IMPLICIT_DELETE_DEPENDENCIES, ot as runStackBuffered, p as ProviderRegistry, pt as withStackName, q as ResourceUpdateNotSupportedError, r as DeployEngine, s as IAMRoleProvider, st as getLiveRenderer, t as DEFAULT_RESOURCE_TIMEOUT_MS, tt as normalizeAwsError, u as matchesCdkPath, ut as generateResourceName, v as DagBuilder, w as WorkGraph, x as S3StateBackend, y as TemplateParser, z as CdkdError } from "./deploy-engine-D44ADMVs.js";
 import { createHash, createPublicKey, createVerify, randomBytes, randomUUID } 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 } from "@aws-sdk/client-s3";
+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";
 import { CreateQueueCommand, DeleteQueueCommand, GetQueueAttributesCommand, GetQueueUrlCommand, ListQueueTagsCommand, ListQueuesCommand, QueueDoesNotExist, SQSClient, SetQueueAttributesCommand, TagQueueCommand, UntagQueueCommand } from "@aws-sdk/client-sqs";
 import { CreateTopicCommand, DeleteTopicCommand, GetSubscriptionAttributesCommand, GetTopicAttributesCommand, ListTagsForResourceCommand, ListTopicsCommand, NotFoundException, SNSClient, SetTopicAttributesCommand, SubscribeCommand, TagResourceCommand, UnsubscribeCommand, UntagResourceCommand } from "@aws-sdk/client-sns";
@@ -870,6 +870,339 @@ function createListCommand() {
 	return cmd;
 }
 
+//#endregion
+//#region src/state/export-index-store.ts
+/**
+* Export index store — persistent global index of `Fn::ImportValue`
+* resolvable exports across all cdkd-managed stacks in a region.
+*
+* Concept: CFn's `cloudformation:ListExports` API is internally backed by
+* an index that lets the producer's Output be looked up by export name in
+* O(1) regardless of how many stacks exist. cdkd mirrors that pattern via
+* `s3://{bucket}/{prefix}/_index/{region}/exports.json` so the resolver
+* doesn't pay the O(N) state-bucket scan on every `Fn::ImportValue`.
+*
+* Roles:
+* - **state.json** (per-stack) is the canonical source of truth for a
+*   stack's outputs + imports. Always written / read with optimistic
+*   locking.
+* - **exports.json** (per-region, in this module) is a DERIVED VIEW used
+*   only as a perf hint. It can be rebuilt from state.json at any time
+*   and is allowed to drift briefly. Strong-reference safety checks
+*   never trust the index — they always re-scan state.json.
+*
+* Failure mode summary:
+* - Index missing → auto-rebuild from state.json on first access.
+* - Index corrupt → log warning, auto-rebuild.
+* - Index stale (post-deploy index update failed) → next resolve's miss
+*   triggers fallback scan; if found, the entry is patched into the
+*   index incrementally.
+* - Two cdkd processes writing concurrently → S3 If-Match optimistic
+*   lock + bounded retry. After exhaustion, the writer logs warn and
+*   continues; the index becomes stale until the next deploy/destroy
+*   updates it.
+*/
+/** Schema version for the exports index file. Separate from state.json's version. */
+const EXPORT_INDEX_VERSION = 1;
+const DEFAULT_OPTIONS = {
+	maxWriteRetries: 5,
+	initialBackoffMs: 100,
+	maxBackoffMs: 1e3
+};
+var ExportIndexStore = class {
+	logger = getLogger().child("ExportIndexStore");
+	s3Client;
+	bucket;
+	prefix;
+	region;
+	stateBackend;
+	loadState = { kind: "unloaded" };
+	opts;
+	/**
+	* In-process serializer for write paths (`updateForStack`,
+	* `patchEntry`, `removeStack`). The S3 `If-Match` etag prevents
+	* cross-process data loss, but within ONE cdkd process the
+	* default `cdkd deploy --all --stack-concurrency > 1` topology
+	* lets multiple per-stack writes race on the same etag — they
+	* would all read the same loaded snapshot, all attempt to write
+	* with that etag, all but one fail with PreconditionFailed, all
+	* retry, and burn through the bounded retry budget for no good
+	* reason. Serializing write paths via this chained promise lets
+	* the etag race only fire across processes (cross-app concurrency)
+	* where it actually matters. Reads (`lookup`) remain unsynchronized.
+	*/
+	writeChain = Promise.resolve();
+	constructor(s3Client, bucket, prefix, region, stateBackend, opts = {}) {
+		this.s3Client = s3Client;
+		this.bucket = bucket;
+		this.prefix = prefix;
+		this.region = region;
+		this.stateBackend = stateBackend;
+		this.opts = {
+			...DEFAULT_OPTIONS,
+			...opts
+		};
+	}
+	/** S3 key for this region's index file. */
+	indexKey() {
+		return `${this.prefix}/_index/${this.region}/exports.json`;
+	}
+	/**
+	* Look up an exported value by name. Returns the cached entry on hit,
+	* or `undefined` on miss. The caller is responsible for falling back
+	* to a state.json scan and (if found) patching the index via
+	* {@link patchEntry}.
+	*/
+	async lookup(exportName) {
+		await this.ensureLoaded();
+		if (this.loadState.kind !== "loaded") return;
+		return this.loadState.entries.get(exportName);
+	}
+	/**
+	* Replace all entries for `(stackName, producerRegion)` with the
+	* supplied `outputs`. Used after a successful deploy save. Writes
+	* the updated index to S3 under an If-Match optimistic lock,
+	* retrying on conflict.
+	*
+	* If `outputs` is empty, every entry currently owned by this stack
+	* in this region is removed.
+	*
+	* Best-effort: on persistent retry exhaustion the in-memory map is
+	* still updated locally (so this session sees a consistent view) and
+	* a warning is logged. The on-disk index will be repaired by the
+	* next successful update or by a rebuild on miss.
+	*/
+	async updateForStack(stackName, producerRegion, outputs) {
+		await this.enqueueWrite("update", () => this.applyStackUpdate(stackName, producerRegion, outputs));
+	}
+	/**
+	* Patch a single entry into the index after a `lookup` miss fell back
+	* to a state.json scan and found the value. Lightweight write that
+	* does NOT require a full rebuild.
+	*/
+	async patchEntry(exportName, entry) {
+		await this.enqueueWrite("patch", () => this.applyPatch(exportName, entry));
+	}
+	/**
+	* Drop all entries owned by `(stackName, producerRegion)`. Used after
+	* a successful destroy. Same retry / best-effort semantics as
+	* `updateForStack`. Filtering by both stack AND region is symmetric
+	* with the update path so a stack that was re-deployed to a new
+	* region keeps its old-region entries (the user must destroy in the
+	* old region too to drop them).
+	*/
+	async removeStack(stackName, producerRegion) {
+		await this.enqueueWrite("remove", () => this.applyRemoveStack(stackName, producerRegion));
+	}
+	/**
+	* Serialize write paths within a single process. Chains every write
+	* onto a tail Promise so two concurrent `updateForStack` calls don't
+	* race on the same etag inside the same cdkd. The S3 If-Match retry
+	* remains as cross-process protection.
+	*/
+	async enqueueWrite(label, op) {
+		const next = this.writeChain.then(() => this.runWithRetry(label, op));
+		this.writeChain = next.catch(() => {});
+		return next;
+	}
+	/**
+	* Force a rebuild from state.json files, overwriting whatever is in
+	* the on-disk index. Useful for recovery and for tests.
+	*/
+	async rebuild() {
+		const entries = await this.rebuildFromStateBackend();
+		const next = {
+			indexVersion: 1,
+			region: this.region,
+			exports: Object.fromEntries(entries),
+			lastModified: Date.now()
+		};
+		const etag = await this.writeIndex(next, void 0);
+		this.loadState = {
+			kind: "loaded",
+			etag,
+			entries
+		};
+	}
+	async ensureLoaded() {
+		if (this.loadState.kind === "loaded") return;
+		if (this.loadState.kind === "loading") {
+			await this.loadState.promise;
+			return;
+		}
+		const promise = this.doLoad();
+		this.loadState = {
+			kind: "loading",
+			promise
+		};
+		await promise;
+	}
+	async doLoad() {
+		try {
+			const raw = await this.readIndexRaw();
+			if (raw === null) {
+				this.logger.info("Exports index missing; rebuilding from state.json files");
+				await this.rebuild();
+				return;
+			}
+			const { body, etag } = raw;
+			let parsed;
+			try {
+				parsed = JSON.parse(body);
+			} catch (err) {
+				this.logger.warn(`Exports index corrupt (${err instanceof Error ? err.message : String(err)}); rebuilding from state.json files`);
+				await this.rebuild();
+				return;
+			}
+			if (typeof parsed.indexVersion !== "number" || parsed.indexVersion > 1) throw new Error(`Exports index uses indexVersion ${String(parsed.indexVersion)} which is newer than this cdkd binary supports (max ${1}). Upgrade cdkd.`);
+			const entries = /* @__PURE__ */ new Map();
+			for (const [name, entry] of Object.entries(parsed.exports ?? {})) entries.set(name, entry);
+			this.loadState = {
+				kind: "loaded",
+				etag,
+				entries
+			};
+		} catch (err) {
+			this.loadState = { kind: "unloaded" };
+			throw err;
+		}
+	}
+	async readIndexRaw() {
+		try {
+			const response = await this.s3Client.send(new GetObjectCommand({
+				Bucket: this.bucket,
+				Key: this.indexKey()
+			}));
+			return {
+				body: await response.Body?.transformToString() ?? "",
+				etag: response.ETag
+			};
+		} catch (err) {
+			if (this.isNoSuchKey(err)) return null;
+			throw err;
+		}
+	}
+	async writeIndex(next, expectedEtag) {
+		const body = JSON.stringify(next, null, 2);
+		return (await this.s3Client.send(new PutObjectCommand({
+			Bucket: this.bucket,
+			Key: this.indexKey(),
+			Body: body,
+			ContentLength: Buffer.byteLength(body),
+			ContentType: "application/json",
+			...expectedEtag && { IfMatch: expectedEtag }
+		}))).ETag;
+	}
+	/**
+	* Re-read state.json for every stack in the bucket and assemble a
+	* fresh `exportName → entry` map. Region-scoped — only state files
+	* in this index's region contribute.
+	*/
+	async rebuildFromStateBackend() {
+		const inRegion = (await this.stateBackend.listStacks()).filter((ref) => ref.region === this.region);
+		this.logger.debug(`Rebuilding exports index for region '${this.region}' from ${inRegion.length} stack state file(s)`);
+		const entries = /* @__PURE__ */ new Map();
+		const results = await Promise.all(inRegion.map(async (ref) => {
+			try {
+				return {
+					ref,
+					state: (await this.stateBackend.getState(ref.stackName, ref.region ?? this.region))?.state
+				};
+			} catch (err) {
+				this.logger.warn(`Failed to read state for ${ref.stackName} (${ref.region ?? ""}) during index rebuild: ${err instanceof Error ? err.message : String(err)}`);
+				return {
+					ref,
+					state: null
+				};
+			}
+		}));
+		for (const { ref, state } of results) {
+			if (!state || !state.outputs) continue;
+			const region = ref.region ?? this.region;
+			for (const [name, value] of Object.entries(state.outputs)) entries.set(name, {
+				value,
+				producerStack: ref.stackName,
+				producerRegion: region
+			});
+		}
+		return entries;
+	}
+	async applyStackUpdate(stackName, producerRegion, outputs) {
+		await this.ensureLoaded();
+		if (this.loadState.kind !== "loaded") return;
+		const next = new Map(this.loadState.entries);
+		for (const [name, entry] of next) if (entry.producerStack === stackName && entry.producerRegion === producerRegion) next.delete(name);
+		for (const [name, value] of Object.entries(outputs)) next.set(name, {
+			value,
+			producerStack: stackName,
+			producerRegion
+		});
+		await this.persist(next);
+	}
+	async applyPatch(exportName, entry) {
+		await this.ensureLoaded();
+		if (this.loadState.kind !== "loaded") return;
+		const next = new Map(this.loadState.entries);
+		next.set(exportName, entry);
+		await this.persist(next);
+	}
+	async applyRemoveStack(stackName, producerRegion) {
+		await this.ensureLoaded();
+		if (this.loadState.kind !== "loaded") return;
+		const next = new Map(this.loadState.entries);
+		let changed = false;
+		for (const [name, entry] of next) if (entry.producerStack === stackName && entry.producerRegion === producerRegion) {
+			next.delete(name);
+			changed = true;
+		}
+		if (!changed) return;
+		await this.persist(next);
+	}
+	async persist(entries) {
+		if (this.loadState.kind !== "loaded") return;
+		const file = {
+			indexVersion: 1,
+			region: this.region,
+			exports: Object.fromEntries(entries),
+			lastModified: Date.now()
+		};
+		const etag = await this.writeIndex(file, this.loadState.etag);
+		this.loadState = {
+			kind: "loaded",
+			etag,
+			entries
+		};
+	}
+	async runWithRetry(label, op) {
+		let lastErr;
+		for (let attempt = 0; attempt < this.opts.maxWriteRetries; attempt++) try {
+			await op();
+			return;
+		} catch (err) {
+			lastErr = err;
+			if (this.isPreconditionFailed(err)) {
+				this.loadState = { kind: "unloaded" };
+				const backoff = Math.min(this.opts.initialBackoffMs * 2 ** attempt, this.opts.maxBackoffMs);
+				await new Promise((resolve) => setTimeout(resolve, backoff));
+				continue;
+			}
+			this.logger.warn(`Exports index ${label} failed (non-retryable): ${err instanceof Error ? err.message : String(err)}; continuing without index update`);
+			return;
+		}
+		this.logger.warn(`Exports index ${label} exhausted ${this.opts.maxWriteRetries} retries due to concurrent writers; continuing without index update. Last error: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+	}
+	isNoSuchKey(err) {
+		if (!err || typeof err !== "object") return false;
+		const e = err;
+		return e.name === "NoSuchKey" || e.$metadata?.httpStatusCode === 404;
+	}
+	isPreconditionFailed(err) {
+		if (!err || typeof err !== "object") return false;
+		const e = err;
+		return e.name === "PreconditionFailed" || e.$metadata?.httpStatusCode === 412;
+	}
+};
+
 //#endregion
 //#region src/provisioning/providers/iam-policy-provider.ts
 /**
@@ -27302,13 +27635,15 @@ async function deployCommand(stacks, options) {
 		...options.profile && { profile: options.profile }
 	});
 	setAwsClients(awsClients);
-	await new S3StateBackend(awsClients.s3, {
+	const preflightStateBackend = new S3StateBackend(awsClients.s3, {
 		bucket: stateBucket,
 		prefix: options.statePrefix
 	}, {
 		region,
 		...options.profile && { profile: options.profile }
-	}).verifyBucketExists();
+	});
+	await preflightStateBackend.verifyBucketExists();
+	const exportIndexStore = new ExportIndexStore(awsClients.s3, stateBucket, options.statePrefix, region, preflightStateBackend);
 	let deployInterrupted = false;
 	const topLevelSigintHandler = () => {
 		if (deployInterrupted) {
@@ -27442,7 +27777,7 @@ async function deployCommand(stacks, options) {
 					...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
 					...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
 					...options.resourceTimeout?.perTypeMs && { resourceTimeoutByType: options.resourceTimeout.perTypeMs }
-				}, stackRegion).deploy(stackInfo.stackName, stackInfo.template);
+				}, stackRegion, exportIndexStore).deploy(stackInfo.stackName, stackInfo.template);
 				logger.info("\nDeployment Summary:");
 				logger.info(`  Stack: ${deployResult.stackName}`);
 				logger.info(`  Created: ${deployResult.created}`);
@@ -27612,7 +27947,7 @@ async function diffCommand(stacks, options) {
 				region: stackRegion,
 				resources: {},
 				outputs: {},
-				version: 3,
+				version: 4,
 				lastModified: Date.now()
 			};
 			if (!stateResult) logger.debug(`No existing state for ${stackInfo.stackName} (${stackRegion})`);
@@ -28643,6 +28978,11 @@ async function runDestroyForStack(stackName, state, ctx) {
 		result.skippedEmpty = true;
 		return result;
 	}
+	const needsStrongRefCheck = !!(state.outputs && Object.keys(state.outputs).length > 0);
+	if (needsStrongRefCheck) {
+		const consumers = await scanActiveConsumers(stackName, regionForState, ctx);
+		if (consumers.length > 0) throw new StackHasActiveImportsError(stackName, regionForState, consumers);
+	}
 	logger.info(`\nResources to be deleted (${resourceCount}):`);
 	for (const [logicalId, resource] of Object.entries(state.resources)) logger.info(`  - ${logicalId} (${resource.resourceType})`);
 	const protectedCount = ctx.removeProtection ? countProtectedResources(state) : 0;
@@ -28685,6 +29025,17 @@ async function runDestroyForStack(stackName, state, ctx) {
 	}
 	logger.info(`\nAcquiring lock for stack ${stackName}...`);
 	await ctx.lockManager.acquireLock(stackName, regionForState, void 0, "destroy");
+	if (needsStrongRefCheck) {
+		const consumers = await scanActiveConsumers(stackName, regionForState, ctx);
+		if (consumers.length > 0) {
+			try {
+				await ctx.lockManager.releaseLock(stackName, regionForState);
+			} catch (releaseErr) {
+				logger.warn(`Failed to release lock after strong-ref refusal: ${releaseErr instanceof Error ? releaseErr.message : String(releaseErr)}`);
+			}
+			throw new StackHasActiveImportsError(stackName, regionForState, consumers);
+		}
+	}
 	const renderer = getLiveRenderer();
 	renderer.start();
 	try {
@@ -28803,6 +29154,7 @@ async function runDestroyForStack(stackName, state, ctx) {
 		if (result.errorCount === 0) {
 			await ctx.stateBackend.deleteState(stackName, regionForState);
 			logger.debug("State deleted");
+			if (ctx.exportIndexStore) await ctx.exportIndexStore.removeStack(stackName, regionForState);
 		} else logger.warn(`${result.errorCount} resource(s) failed to delete. State preserved.`);
 		if (result.errorCount === 0) logger.info(`\n✓ Stack ${stackName} destroyed (${result.deletedCount} deleted, ${result.errorCount} errors)`);
 		else logger.warn(`\n⚠ Stack ${stackName} partially destroyed (${result.deletedCount} deleted, ${result.errorCount} errors). State preserved — re-run 'cdkd destroy' / 'cdkd state destroy' to clean up.`);
@@ -28819,6 +29171,38 @@ async function runDestroyForStack(stackName, state, ctx) {
 	}
 	return result;
 }
+/**
+* Strong-reference scan: read every other stack's state.json from the
+* state bucket and check whether any of its `imports[]` entries names
+* `producerStack`. Returns the list of offending consumers (possibly
+* empty).
+*
+* NEVER trusts the persistent exports index — a stale index could miss
+* a freshly-recorded consumer and let a destructive destroy through.
+* The cost is one `listStacks` + N parallel GETs at destroy time only
+* (not the deploy hot path), which the user-facing UX rationalizes as
+* the "destroy is slow OK" trade-off (Issue #343).
+*/
+async function scanActiveConsumers(producerStack, producerRegion, ctx) {
+	const refs = await ctx.stateBackend.listStacks();
+	return (await Promise.all(refs.map(async (ref) => {
+		const region = ref.region ?? ctx.baseRegion;
+		if (ref.stackName === producerStack && region === producerRegion) return null;
+		try {
+			const imports = (await ctx.stateBackend.getState(ref.stackName, region))?.state.imports;
+			if (!imports || imports.length === 0) return null;
+			const matches = imports.filter((entry) => entry.sourceStack === producerStack && entry.sourceRegion === producerRegion);
+			if (matches.length === 0) return null;
+			return matches.map((entry) => ({
+				consumerStack: ref.stackName,
+				consumerRegion: region,
+				exportName: entry.exportName
+			}));
+		} catch {
+			return null;
+		}
+	}))).filter((r) => r !== null).flat();
+}
 
 //#endregion
 //#region src/cli/commands/destroy.ts
@@ -28861,6 +29245,7 @@ async function destroyCommand(stackArgs, options) {
 		});
 		await stateBackend.verifyBucketExists();
 		const lockManager = new LockManager(awsClients.s3, stateConfig);
+		const exportIndexStore = new ExportIndexStore(awsClients.s3, stateBucket, options.statePrefix, region, stateBackend);
 		const providerRegistry = new ProviderRegistry();
 		registerAllProviders(providerRegistry);
 		providerRegistry.setCustomResourceResponseBucket(stateBucket);
@@ -28957,6 +29342,7 @@ async function destroyCommand(stackArgs, options) {
 				stateBucket,
 				skipConfirmation: options.yes || options.force,
 				removeProtection: options.removeProtection === true,
+				exportIndexStore,
 				...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
 				...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
 				...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
@@ -30231,6 +30617,7 @@ async function setupStateBackend(options) {
 		region,
 		bucket,
 		prefix,
+		exportIndexStore: new ExportIndexStore(awsClients.s3, bucket, prefix, region, stateBackend),
 		dispose: () => awsClients.destroy()
 	};
 }
@@ -30702,6 +31089,7 @@ async function stateDestroyCommand(stackArgs, options) {
 					stateBucket: setup.bucket,
 					skipConfirmation: options.yes || options.all === true,
 					removeProtection: options.removeProtection === true,
+					exportIndexStore: setup.exportIndexStore,
 					...options.resourceWarnAfter?.globalMs !== void 0 && { resourceWarnAfterMs: options.resourceWarnAfter.globalMs },
 					...options.resourceTimeout?.globalMs !== void 0 && { resourceTimeoutMs: options.resourceTimeout.globalMs },
 					...options.resourceWarnAfter?.perTypeMs && { resourceWarnAfterByType: options.resourceWarnAfter.perTypeMs },
@@ -31784,7 +32172,7 @@ function buildStackState(stackName, region, rows, templateParser, template, exis
 		};
 	}
 	return {
-		version: 3,
+		version: 4,
 		stackName,
 		region,
 		resources,
@@ -41837,7 +42225,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.96.1");
+	program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.97.0");
 	program.addCommand(createBootstrapCommand());
 	program.addCommand(createSynthCommand());
 	program.addCommand(createListCommand());