@go-to-k/cdkd 0.7.0 → 0.8.0

package/dist/cli.js

@@ -3205,6 +3205,14 @@ import {
   ListObjectsV2Command,
   NoSuchKey
 } from "@aws-sdk/client-s3";
+
+// src/types/state.ts
+var STATE_SCHEMA_VERSION_LEGACY = 1;
+var STATE_SCHEMA_VERSION_CURRENT = 2;
+
+// src/state/s3-state-backend.ts
+var LEGACY_KEY_DEPTH = 2;
+var NEW_KEY_DEPTH = 3;
 var S3StateBackend = class {
   constructor(s3Client, config) {
     this.s3Client = s3Client;
@@ -3212,9 +3220,16 @@ var S3StateBackend = class {
   }
   logger = getLogger().child("S3StateBackend");
   /**
-   * Get the S3 key for a stack's state file
+   * Get the new (region-scoped) S3 key for a stack's state file.
+   */
+  getStateKey(stackName, region) {
+    return `${this.config.prefix}/${stackName}/${region}/state.json`;
+  }
+  /**
+   * Get the legacy (pre-region-prefix) S3 key for a stack's state file.
+   * Used for backwards-compatible reads and for the migration delete.
    */
-  getStateKey(stackName) {
+  getLegacyStateKey(stackName) {
     return `${this.config.prefix}/${stackName}/state.json`;
   }
   /**
@@ -3240,101 +3255,143 @@ var S3StateBackend = class {
     }
   }
   /**
-   * Check if state exists for a stack
-   */
-  async stateExists(stackName) {
-    const key = this.getStateKey(stackName);
-    try {
-      await this.s3Client.send(
-        new HeadObjectCommand2({
-          Bucket: this.config.bucket,
-          Key: key
-        })
-      );
+   * Check if state exists for a stack in the given region.
+   *
+   * Returns true for either layout: the new region-scoped key, or the legacy
+   * key when its embedded `region` matches the requested region. This lets
+   * `cdkd state rm <stack> --region X` and `cdkd destroy <stack>` see legacy
+   * state without forcing a write-through migration first.
+   */
+  async stateExists(stackName, region) {
+    const newKey = this.getStateKey(stackName, region);
+    if (await this.headObject(newKey)) {
       return true;
-    } catch (error) {
-      if (error instanceof NoSuchKey || error.name === "NotFound") {
-        return false;
-      }
-      throw new StateError(
-        `Failed to check if state exists for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
-        error instanceof Error ? error : void 0
-      );
     }
+    return this.legacyMatchesRegion(stackName, region);
   }
   /**
-   * Get state for a stack
+   * Get state for a stack, transparently falling back to the legacy key.
+   *
+   * Lookup order:
+   * 1. `{prefix}/{stackName}/{region}/state.json` (current `version: 2` key).
+   * 2. `{prefix}/{stackName}/state.json` (legacy `version: 1` key) — only
+   *    accepted if its embedded `region` matches the requested region.
    *
-   * Note: S3 returns ETag with surrounding quotes (e.g., "abc123").
-   * We preserve the quotes as they are required for IfMatch conditions.
+   * When a legacy hit is returned, `migrationPending` is `true`. Callers that
+   * subsequently `saveState` automatically migrate by writing the new key and
+   * deleting the legacy one (see `saveState`'s `legacyMigration` argument).
+   *
+   * Note: S3 returns ETag with surrounding quotes (e.g., `"abc123"`). We
+   * preserve the quotes — they are required for `IfMatch` conditions.
    */
-  async getState(stackName) {
-    const key = this.getStateKey(stackName);
+  async getState(stackName, region) {
+    const newKey = this.getStateKey(stackName, region);
     try {
-      this.logger.debug(`Getting state for stack: ${stackName}`);
+      this.logger.debug(`Getting state for stack: ${stackName} (${region})`);
       const response = await this.s3Client.send(
         new GetObjectCommand({
           Bucket: this.config.bucket,
-          Key: key
+          Key: newKey
         })
       );
       if (!response.Body) {
-        throw new StateError(`State file for stack '${stackName}' has no body`);
+        throw new StateError(`State file for stack '${stackName}' (${region}) has no body`);
       }
       if (!response.ETag) {
-        throw new StateError(`State file for stack '${stackName}' has no ETag`);
+        throw new StateError(`State file for stack '${stackName}' (${region}) has no ETag`);
       }
       const bodyString = await response.Body.transformToString();
-      const state = JSON.parse(bodyString);
-      this.logger.debug(`Retrieved state for stack: ${stackName}, ETag: ${response.ETag}`);
-      return {
-        state,
-        etag: response.ETag
-      };
+      const state = this.parseStateBody(bodyString, stackName);
+      this.logger.debug(`Retrieved state: ${stackName} (${region}), ETag: ${response.ETag}`);
+      return { state, etag: response.ETag };
     } catch (error) {
-      if (error instanceof NoSuchKey || error.name === "NoSuchKey") {
-        this.logger.debug(`No existing state for stack: ${stackName}`);
-        return null;
-      }
-      if (error instanceof StateError) {
-        throw error;
+      if (!isNoSuchKey(error)) {
+        if (error instanceof StateError)
+          throw error;
+        throw new StateError(
+          `Failed to get state for stack '${stackName}' (${region}): ${error instanceof Error ? error.message : String(error)}`,
+          error instanceof Error ? error : void 0
+        );
       }
-      throw new StateError(
-        `Failed to get state for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
-        error instanceof Error ? error : void 0
+      this.logger.debug(`No state at new key for stack: ${stackName} (${region})`);
+    }
+    const legacy = await this.tryGetLegacy(stackName, region);
+    if (legacy) {
+      this.logger.warn(
+        `Loaded legacy state for stack '${stackName}' from '${this.getLegacyStateKey(stackName)}'. It will be migrated to the region-scoped layout on next save.`
       );
+      return { ...legacy, migrationPending: true };
     }
+    return null;
   }
   /**
-   * Save state for a stack with optimistic locking
+   * Save state for a stack with optimistic locking.
+   *
+   * Always writes to the new region-scoped key. The state body is rewritten
+   * with `version: 2` and the supplied region.
+   *
+   * If the caller observed `migrationPending: true` from `getState`, it
+   * should pass the legacy ETag back via `expectedEtag` AND set
+   * `migrateLegacy: true`. After the new key is written successfully, the
+   * legacy key is deleted to complete migration. The legacy delete is a
+   * best-effort follow-up — a failure is logged but does not unwind the new
+   * write.
    *
    * @param stackName Stack name
+   * @param region Target region (load-bearing — part of the S3 key)
    * @param state State to save
-   * @param expectedEtag Expected ETag for optimistic locking (optional for new state).
-   *                     Must include quotes if provided (e.g., "abc123")
-   * @returns New ETag (with quotes, e.g., "abc123")
-   */
-  async saveState(stackName, state, expectedEtag) {
-    const key = this.getStateKey(stackName);
+   * @param options Optimistic-lock ETag + legacy-migration flag
+   * @returns New ETag (with quotes, e.g., `"abc123"`)
+   */
+  async saveState(stackName, region, state, options = {}) {
+    const newKey = this.getStateKey(stackName, region);
+    const { expectedEtag, migrateLegacy } = options;
+    const body = {
+      ...state,
+      version: STATE_SCHEMA_VERSION_CURRENT,
+      stackName,
+      region
+    };
     try {
       this.logger.debug(
-        `Saving state for stack: ${stackName}${expectedEtag ? `, expected ETag: ${expectedEtag}` : ""}`
+        `Saving state: ${stackName} (${region})${expectedEtag ? `, expected ETag: ${expectedEtag}` : ""}`
       );
-      const body = JSON.stringify(state, null, 2);
+      const bodyString = JSON.stringify(body, null, 2);
       const response = await this.s3Client.send(
         new PutObjectCommand2({
           Bucket: this.config.bucket,
-          Key: key,
-          Body: body,
-          ContentLength: Buffer.byteLength(body),
+          Key: newKey,
+          Body: bodyString,
+          ContentLength: Buffer.byteLength(bodyString),
           ContentType: "application/json",
-          ...expectedEtag && { IfMatch: expectedEtag }
+          // The legacy ETag is for a different key; only forward it when we're
+          // updating in-place at the new key.
+          ...!migrateLegacy && expectedEtag && { IfMatch: expectedEtag }
         })
       );
       if (!response.ETag) {
-        throw new StateError(`No ETag returned after saving state for stack '${stackName}'`);
+        throw new StateError(
+          `No ETag returned after saving state for stack '${stackName}' (${region})`
+        );
+      }
+      this.logger.debug(`State saved: ${stackName} (${region}), new ETag: ${response.ETag}`);
+      if (migrateLegacy) {
+        try {
+          await this.s3Client.send(
+            new DeleteObjectCommand({
+              Bucket: this.config.bucket,
+              Key: this.getLegacyStateKey(stackName)
+            })
+          );
+          this.logger.info(
+            `Migrated state for stack '${stackName}' to region-scoped layout (${region})`
+          );
+        } catch (deleteError) {
+          this.logger.warn(
+            `Migrated stack '${stackName}' to new key, but failed to delete legacy key: ${deleteError instanceof Error ? deleteError.message : String(deleteError)}`
+          );
+        }
       }
-      this.logger.debug(`State saved for stack: ${stackName}, new ETag: ${response.ETag}`);
       return response.ETag;
     } catch (error) {
       if (error.name === "PreconditionFailed") {
@@ -3343,63 +3400,230 @@ var S3StateBackend = class {
         );
       }
       throw new StateError(
-        `Failed to save state for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to save state for stack '${stackName}' (${region}): ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error : void 0
       );
     }
   }
   /**
-   * Delete state for a stack
+   * Delete state for a stack in the given region.
+   *
+   * Removes both the new key and the legacy key (if present). Legacy removal
+   * is region-conditional: a legacy state file with a different `region`
+   * field is left alone.
    */
-  async deleteState(stackName) {
-    const key = this.getStateKey(stackName);
+  async deleteState(stackName, region) {
     try {
-      this.logger.debug(`Deleting state for stack: ${stackName}`);
+      this.logger.debug(`Deleting state: ${stackName} (${region})`);
       await this.s3Client.send(
         new DeleteObjectCommand({
           Bucket: this.config.bucket,
-          Key: key
+          Key: this.getStateKey(stackName, region)
         })
       );
-      this.logger.debug(`State deleted for stack: ${stackName}`);
+      if (await this.legacyMatchesRegion(stackName, region)) {
+        await this.s3Client.send(
+          new DeleteObjectCommand({
+            Bucket: this.config.bucket,
+            Key: this.getLegacyStateKey(stackName)
+          })
+        );
+        this.logger.debug(`Deleted legacy state for stack: ${stackName}`);
+      }
+      this.logger.debug(`State deleted: ${stackName} (${region})`);
     } catch (error) {
       throw new StateError(
-        `Failed to delete state for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to delete state for stack '${stackName}' (${region}): ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error : void 0
       );
     }
   }
   /**
-   * List all stacks with state
+   * List all stacks with state in the bucket.
+   *
+   * Returns one `{stackName, region}` pair per state file. Both layouts
+   * are enumerated:
+   *
+   * - `{prefix}/{stackName}/{region}/state.json` (new) — `region` is the
+   *   path segment.
+   * - `{prefix}/{stackName}/state.json` (legacy) — `region` is read from the
+   *   state body when present, otherwise `undefined`.
+   *
+   * Pairs are deduplicated by `(stackName, region)` so a stack mid-migration
+   * shows up exactly once.
    */
   async listStacks() {
     try {
       this.logger.debug("Listing all stacks");
+      const prefix = `${this.config.prefix}/`;
+      const refs = [];
+      const seen = /* @__PURE__ */ new Set();
+      let continuationToken;
+      do {
+        const response = await this.s3Client.send(
+          new ListObjectsV2Command({
+            Bucket: this.config.bucket,
+            Prefix: prefix,
+            ...continuationToken && { ContinuationToken: continuationToken }
+          })
+        );
+        for (const obj of response.Contents ?? []) {
+          const key = obj.Key;
+          if (!key)
+            continue;
+          if (!key.endsWith("/state.json"))
+            continue;
+          const rest = key.slice(prefix.length);
+          const segments = rest.split("/");
+          if (segments.length === NEW_KEY_DEPTH) {
+            const [stackName, region] = segments;
+            if (!stackName || !region)
+              continue;
+            const dedupeKey = `${stackName}\0${region}`;
+            if (!seen.has(dedupeKey)) {
+              seen.add(dedupeKey);
+              refs.push({ stackName, region });
+            }
+            continue;
+          }
+          if (segments.length === LEGACY_KEY_DEPTH) {
+            const [stackName] = segments;
+            if (!stackName)
+              continue;
+            const region = await this.readLegacyRegion(stackName);
+            const dedupeKey = `${stackName}\0${region ?? ""}`;
+            if (!seen.has(dedupeKey)) {
+              seen.add(dedupeKey);
+              refs.push({ stackName, ...region ? { region } : {} });
+            }
+          }
+        }
+        continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+      } while (continuationToken);
+      this.logger.debug(`Found ${refs.length} stack(s) across regions`);
+      return refs;
+    } catch (error) {
+      throw new StateError(
+        `Failed to list stacks: ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * HeadObject probe — returns true on 200, false on NotFound. Other errors
+   * propagate so we don't accidentally swallow IAM denials.
+   */
+  async headObject(key) {
+    try {
+      await this.s3Client.send(
+        new HeadObjectCommand2({
+          Bucket: this.config.bucket,
+          Key: key
+        })
+      );
+      return true;
+    } catch (error) {
+      if (isNoSuchKey(error) || error.name === "NotFound") {
+        return false;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Read the legacy state's `region` field. Used for region matching during
+   * `stateExists` / `deleteState` and for assigning a region to legacy
+   * entries during `listStacks`.
+   */
+  async readLegacyRegion(stackName) {
+    try {
+      const response = await this.s3Client.send(
+        new GetObjectCommand({
+          Bucket: this.config.bucket,
+          Key: this.getLegacyStateKey(stackName)
+        })
+      );
+      if (!response.Body)
+        return void 0;
+      const bodyString = await response.Body.transformToString();
+      const state = JSON.parse(bodyString);
+      return typeof state.region === "string" ? state.region : void 0;
+    } catch (error) {
+      if (isNoSuchKey(error))
+        return void 0;
+      this.logger.debug(
+        `Could not read legacy state region for '${stackName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return void 0;
+    }
+  }
+  async legacyMatchesRegion(stackName, region) {
+    const legacyRegion = await this.readLegacyRegion(stackName);
+    return legacyRegion === region;
+  }
+  /**
+   * Try to read the legacy `version: 1` state. Returns null when the legacy
+   * key is missing or its embedded region does not match the caller's region.
+   */
+  async tryGetLegacy(stackName, region) {
+    try {
       const response = await this.s3Client.send(
-        new ListObjectsV2Command({
+        new GetObjectCommand({
           Bucket: this.config.bucket,
-          Prefix: `${this.config.prefix}/`,
-          Delimiter: "/"
+          Key: this.getLegacyStateKey(stackName)
         })
       );
-      if (!response.CommonPrefixes) {
-        return [];
+      if (!response.Body || !response.ETag) {
+        return null;
+      }
+      const bodyString = await response.Body.transformToString();
+      const state = this.parseStateBody(bodyString, stackName);
+      if (state.region && state.region !== region) {
+        this.logger.debug(
+          `Legacy state for stack '${stackName}' has region '${state.region}', not '${region}' \u2014 skipping legacy fallback.`
+        );
+        return null;
       }
-      const stackNames = response.CommonPrefixes.map((prefix) => {
-        const prefixStr = prefix.Prefix || "";
-        const parts = prefixStr.split("/");
-        return parts[parts.length - 2];
-      }).filter((name) => Boolean(name));
-      this.logger.debug(`Found ${stackNames.length} stacks`);
-      return stackNames;
+      return { state, etag: response.ETag };
     } catch (error) {
+      if (isNoSuchKey(error))
+        return null;
       throw new StateError(
-        `Failed to list stacks: ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to get legacy state for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Parse a state body and validate the schema version. Future-proofs against
+   * a binary that predates schema version `N` reading a `version: N+1` blob:
+   * the old binary would otherwise treat unknown fields as defaults and
+   * silently lose data on the next save.
+   */
+  parseStateBody(bodyString, stackName) {
+    let parsed;
+    try {
+      parsed = JSON.parse(bodyString);
+    } catch (error) {
+      throw new StateError(
+        `State file for stack '${stackName}' is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error : void 0
       );
     }
+    const v = parsed.version;
+    if (v !== STATE_SCHEMA_VERSION_LEGACY && v !== STATE_SCHEMA_VERSION_CURRENT && v !== void 0) {
+      throw new StateError(
+        `Unsupported state schema version ${String(v)} for stack '${stackName}'. This cdkd binary supports versions ${String(STATE_SCHEMA_VERSION_LEGACY)} and ${String(STATE_SCHEMA_VERSION_CURRENT)}. Upgrade cdkd to a version that supports schema ${String(v)}.`
+      );
+    }
+    return parsed;
   }
 };
+function isNoSuchKey(error) {
+  if (error instanceof NoSuchKey)
+    return true;
+  const name = error?.name;
+  return name === "NoSuchKey";
+}
 
 // src/state/lock-manager.ts
 import {
@@ -3420,10 +3644,24 @@ var LockManager = class {
   logger = getLogger().child("LockManager");
   ttlMs;
   /**
-   * Get the S3 key for a stack's lock file
+   * Get the S3 key for a stack's lock file.
+   *
+   * Locks are region-scoped, mirroring the state key layout
+   * (`{prefix}/{stackName}/{region}/lock.json`). Two regions of the same
+   * stackName can therefore be operated on in parallel without contention,
+   * matching cdkd's parallel execution model.
+   *
+   * The `region` argument is required for new callers; for backwards
+   * compatibility with `state list --long` (which only sees stack names),
+   * passing `undefined` falls back to the legacy `{prefix}/{stackName}/lock.json`
+   * key — that mode is purely for legacy lock cleanup and is NOT used by
+   * deploy / destroy / diff anymore.
    */
-  getLockKey(stackName) {
-    return `${this.config.prefix}/${stackName}/lock.json`;
+  getLockKey(stackName, region) {
+    if (region === void 0) {
+      return `${this.config.prefix}/${stackName}/lock.json`;
+    }
+    return `${this.config.prefix}/${stackName}/${region}/lock.json`;
   }
   /**
    * Get default lock owner identifier
@@ -3462,11 +3700,12 @@ var LockManager = class {
    * If an expired lock exists, it will be cleaned up and re-acquired.
    *
    * @param stackName Stack name
+   * @param region Target region (lock key is region-scoped)
    * @param owner Lock owner identifier (defaults to user@hostname:pid)
    * @param operation Operation being performed (e.g., "deploy", "destroy")
    */
-  async acquireLock(stackName, owner, operation) {
-    const key = this.getLockKey(stackName);
+  async acquireLock(stackName, region, owner, operation) {
+    const key = this.getLockKey(stackName, region);
     const lockOwner = owner || this.getDefaultOwner();
     const now = Date.now();
     const lockInfo = {
@@ -3476,7 +3715,7 @@ var LockManager = class {
       ...operation && { operation }
     };
     try {
-      this.logger.debug(`Attempting to acquire lock for stack: ${stackName}`);
+      this.logger.debug(`Attempting to acquire lock for stack: ${stackName} (${region})`);
       const lockBody = JSON.stringify(lockInfo, null, 2);
       await this.s3Client.send(
         new PutObjectCommand3({
@@ -3489,17 +3728,17 @@ var LockManager = class {
           // Only succeed if object doesn't exist
         })
       );
-      this.logger.debug(`Lock acquired for stack: ${stackName}, owner: ${lockOwner}`);
+      this.logger.debug(`Lock acquired for stack: ${stackName} (${region}), owner: ${lockOwner}`);
       return true;
     } catch (error) {
       if (error instanceof S3ServiceException && error.name === "PreconditionFailed") {
-        this.logger.debug(`Lock already exists for stack: ${stackName}`);
-        const existingLock = await this.getLockInfo(stackName);
+        this.logger.debug(`Lock already exists for stack: ${stackName} (${region})`);
+        const existingLock = await this.getLockInfo(stackName, region);
         if (existingLock && this.isLockExpired(existingLock)) {
           this.logger.info(
-            `Expired lock detected for stack: ${stackName} (owner: ${existingLock.owner}, expired ${this.formatDuration(now - existingLock.expiresAt)} ago). Cleaning up...`
+            `Expired lock detected for stack: ${stackName} (${region}, owner: ${existingLock.owner}, expired ${this.formatDuration(now - existingLock.expiresAt)} ago). Cleaning up...`
           );
-          await this.deleteLock(stackName);
+          await this.deleteLock(stackName, region);
           try {
             const retryBody = JSON.stringify(lockInfo, null, 2);
             await this.s3Client.send(
@@ -3513,13 +3752,13 @@ var LockManager = class {
               })
             );
             this.logger.debug(
-              `Lock acquired for stack: ${stackName} after expired lock cleanup, owner: ${lockOwner}`
+              `Lock acquired for stack: ${stackName} (${region}) after expired lock cleanup, owner: ${lockOwner}`
             );
             return true;
           } catch (retryError) {
             if (retryError instanceof S3ServiceException && retryError.name === "PreconditionFailed") {
               this.logger.debug(
-                `Lock was acquired by another process during expired lock cleanup for stack: ${stackName}`
+                `Lock was acquired by another process during expired lock cleanup for stack: ${stackName} (${region})`
               );
               return false;
             }
@@ -3529,16 +3768,20 @@ var LockManager = class {
         return false;
       }
       throw new LockError(
-        `Failed to acquire lock for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to acquire lock for stack '${stackName}' (${region}): ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error : void 0
       );
     }
   }
   /**
-   * Get current lock information
+   * Get current lock information.
+   *
+   * `region` is required for the new region-scoped lock layout. Pass
+   * `undefined` only to inspect a legacy `{prefix}/{stackName}/lock.json`
+   * file (e.g. for state-listing tools that don't yet know the region).
    */
-  async getLockInfo(stackName) {
-    const key = this.getLockKey(stackName);
+  async getLockInfo(stackName, region) {
+    const key = this.getLockKey(stackName, region);
     try {
       this.logger.debug(`Getting lock info for stack: ${stackName}`);
       const response = await this.s3Client.send(
@@ -3576,27 +3819,27 @@ var LockManager = class {
    * not for acquisition decisions — use `acquireLock` for that, which has its
    * own expired-lock cleanup logic.
    */
-  async isLocked(stackName) {
-    const lockInfo = await this.getLockInfo(stackName);
+  async isLocked(stackName, region) {
+    const lockInfo = await this.getLockInfo(stackName, region);
     return lockInfo !== null;
   }
   /**
    * Release a lock for a stack
    */
-  async releaseLock(stackName) {
-    const key = this.getLockKey(stackName);
+  async releaseLock(stackName, region) {
+    const key = this.getLockKey(stackName, region);
     try {
-      this.logger.debug(`Releasing lock for stack: ${stackName}`);
+      this.logger.debug(`Releasing lock for stack: ${stackName} (${region})`);
       await this.s3Client.send(
         new DeleteObjectCommand2({
           Bucket: this.config.bucket,
           Key: key
         })
       );
-      this.logger.debug(`Lock released for stack: ${stackName}`);
+      this.logger.debug(`Lock released for stack: ${stackName} (${region})`);
     } catch (error) {
       throw new LockError(
-        `Failed to release lock for stack '${stackName}': ${error instanceof Error ? error.message : String(error)}`,
+        `Failed to release lock for stack '${stackName}' (${region}): ${error instanceof Error ? error.message : String(error)}`,
         error instanceof Error ? error : void 0
       );
     }
@@ -3606,23 +3849,28 @@ var LockManager = class {
    *
    * This is intended for CLI usage (e.g., --force-unlock flag) when a lock
    * is stuck and needs manual intervention.
+   *
+   * Pass `region: undefined` to operate on a legacy
+   * `{prefix}/{stackName}/lock.json` file.
    */
-  async forceReleaseLock(stackName) {
-    const lockInfo = await this.getLockInfo(stackName);
+  async forceReleaseLock(stackName, region) {
+    const lockInfo = await this.getLockInfo(stackName, region);
     if (!lockInfo) {
-      this.logger.warn(`No lock to force release for stack: ${stackName}`);
+      this.logger.warn(
+        `No lock to force release for stack: ${stackName}${region ? ` (${region})` : ""}`
+      );
       return;
     }
     this.logger.warn(
-      `Force releasing lock for stack: ${stackName}, owner: ${lockInfo.owner}${lockInfo.operation ? `, operation: ${lockInfo.operation}` : ""}, expired: ${this.isLockExpired(lockInfo)}`
+      `Force releasing lock for stack: ${stackName}${region ? ` (${region})` : ""}, owner: ${lockInfo.owner}${lockInfo.operation ? `, operation: ${lockInfo.operation}` : ""}, expired: ${this.isLockExpired(lockInfo)}`
     );
-    await this.deleteLock(stackName);
+    await this.deleteLock(stackName, region);
   }
   /**
    * Internal method to delete the lock file from S3
    */
-  async deleteLock(stackName) {
-    const key = this.getLockKey(stackName);
+  async deleteLock(stackName, region) {
+    const key = this.getLockKey(stackName, region);
     await this.s3Client.send(
       new DeleteObjectCommand2({
         Bucket: this.config.bucket,
@@ -3643,28 +3891,28 @@ var LockManager = class {
    * @param maxRetries Maximum number of retries (default: 3)
    * @param retryDelay Delay between retries in milliseconds (default: 2000)
    */
-  async acquireLockWithRetry(stackName, owner, operation, maxRetries = 3, retryDelay = 2e3) {
+  async acquireLockWithRetry(stackName, region, owner, operation, maxRetries = 3, retryDelay = 2e3) {
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      const acquired = await this.acquireLock(stackName, owner, operation);
+      const acquired = await this.acquireLock(stackName, region, owner, operation);
       if (acquired) {
         return;
       }
-      const lockInfo2 = await this.getLockInfo(stackName);
+      const lockInfo2 = await this.getLockInfo(stackName, region);
       if (lockInfo2) {
         const remainingMs = lockInfo2.expiresAt - Date.now();
         if (attempt < maxRetries) {
           this.logger.info(
-            `Stack '${stackName}' is locked by ${lockInfo2.owner}${lockInfo2.operation ? ` (operation: ${lockInfo2.operation})` : ""}. Lock expires in ${this.formatDuration(remainingMs)}. Retrying in ${this.formatDuration(retryDelay)}... (attempt ${attempt + 1}/${maxRetries})`
+            `Stack '${stackName}' (${region}) is locked by ${lockInfo2.owner}${lockInfo2.operation ? ` (operation: ${lockInfo2.operation})` : ""}. Lock expires in ${this.formatDuration(remainingMs)}. Retrying in ${this.formatDuration(retryDelay)}... (attempt ${attempt + 1}/${maxRetries})`
           );
           await new Promise((resolve4) => setTimeout(resolve4, retryDelay));
           continue;
         }
       }
     }
-    const lockInfo = await this.getLockInfo(stackName);
+    const lockInfo = await this.getLockInfo(stackName, region);
     const expiresIn = lockInfo ? this.formatDuration(lockInfo.expiresAt - Date.now()) : "unknown";
     throw new LockError(
-      `Failed to acquire lock for stack '${stackName}' after ${maxRetries + 1} attempts. ` + (lockInfo ? `Locked by: ${lockInfo.owner}${lockInfo.operation ? `, operation: ${lockInfo.operation}` : ""}, expires in: ${expiresIn}. Use --force-unlock to manually release the lock.` : "Lock exists but could not read lock info.")
+      `Failed to acquire lock for stack '${stackName}' (${region}) after ${maxRetries + 1} attempts. ` + (lockInfo ? `Locked by: ${lockInfo.owner}${lockInfo.operation ? `, operation: ${lockInfo.operation}` : ""}, expires in: ${expiresIn}. Use --force-unlock to manually release the lock.` : "Lock exists but could not read lock info.")
     );
   }
 };
@@ -5447,35 +5695,45 @@ var IntrinsicFunctionResolver = class {
     }
     this.logger.debug(`Resolving Fn::ImportValue: ${exportName}`);
     const allStacks = await context.stateBackend.listStacks();
-    this.logger.debug(`Found ${allStacks.length} stacks to search for export: ${exportName}`);
-    for (const stackName of allStacks) {
-      if (context.stackName && stackName === context.stackName) {
-        this.logger.debug(`Skipping current stack: ${stackName}`);
+    this.logger.debug(
+      `Found ${allStacks.length} state record(s) to search for export: ${exportName}`
+    );
+    for (const ref of allStacks) {
+      const { stackName: refStack, region: refRegion } = ref;
+      if (context.stackName && refStack === context.stackName) {
+        this.logger.debug(`Skipping current stack: ${refStack}`);
         continue;
       }
       try {
-        const stateData = await context.stateBackend.getState(stackName);
+        const lookupRegion = refRegion ?? this.resolverRegion ?? "";
+        if (!lookupRegion) {
+          this.logger.debug(
+            `No region available for stack '${refStack}' \u2014 skipping (cdkd cannot read state without a region)`
+          );
+          continue;
+        }
+        const stateData = await context.stateBackend.getState(refStack, lookupRegion);
         if (!stateData) {
-          this.logger.debug(`No state found for stack: ${stackName}`);
+          this.logger.debug(`No state found for stack: ${refStack} (${lookupRegion})`);
           continue;
         }
         const { state } = stateData;
         if (state.outputs && exportName in state.outputs) {
           const value = state.outputs[exportName];
           this.logger.info(
-            `Resolved Fn::ImportValue: ${exportName} = ${JSON.stringify(value)} (from stack: ${stackName})`
+            `Resolved Fn::ImportValue: ${exportName} = ${JSON.stringify(value)} (from stack: ${refStack} / ${lookupRegion})`
           );
           return value;
         }
       } catch (error) {
         this.logger.warn(
-          `Failed to read state for stack ${stackName}: ${error instanceof Error ? error.message : String(error)}`
+          `Failed to read state for stack ${refStack}: ${error instanceof Error ? error.message : String(error)}`
         );
         continue;
       }
     }
     throw new Error(
-      `Fn::ImportValue: export '${exportName}' not found in any stack. Searched ${allStacks.length} stacks. Make sure the exporting stack has been deployed and the Output has an Export.Name property.`
+      `Fn::ImportValue: export '${exportName}' not found in any stack. Searched ${allStacks.length} state record(s). Make sure the exporting stack has been deployed and the Output has an Export.Name property.`
     );
   }
   /**
@@ -26256,7 +26514,11 @@ var DeployEngine = class {
   logger = getLogger().child("DeployEngine");
   resolver;
   interrupted = false;
-  /** Target region for this stack (saved in state for cross-region destroy) */
+  /**
+   * Target region for this stack. Required — load-bearing for the
+   * region-prefixed S3 state key and recorded in state.json for
+   * cross-region destroy.
+   */
   stackRegion;
   /**
    * Deploy a CloudFormation template
@@ -26265,7 +26527,7 @@ var DeployEngine = class {
     const startTime = Date.now();
     this.logger.debug(`Starting deployment for stack: ${stackName}`);
     setCurrentStackName(stackName);
-    await this.lockManager.acquireLockWithRetry(stackName, void 0, "deploy");
+    await this.lockManager.acquireLockWithRetry(stackName, this.stackRegion, void 0, "deploy");
     const renderer = getLiveRenderer();
     renderer.start();
     this.interrupted = false;
@@ -26279,16 +26541,17 @@ var DeployEngine = class {
     };
     process.on("SIGINT", sigintHandler);
     try {
-      const currentStateData = await this.stateBackend.getState(stackName);
+      const currentStateData = await this.stateBackend.getState(stackName, this.stackRegion);
       const currentState = currentStateData?.state ?? {
-        version: 1,
-        ...this.stackRegion && { region: this.stackRegion },
+        version: STATE_SCHEMA_VERSION_CURRENT,
+        region: this.stackRegion,
         stackName,
         resources: {},
         outputs: {},
         lastModified: Date.now()
       };
       const currentEtag = currentStateData?.etag;
+      const migrationPending = currentStateData?.migrationPending ?? false;
       this.logger.debug(
         `Loaded current state: ${Object.keys(currentState.resources).length} resources`
       );
@@ -26374,9 +26637,10 @@ var DeployEngine = class {
         parameterValues,
         conditions,
         currentEtag,
-        progress
+        progress,
+        migrationPending
       );
-      const newEtag = await this.stateBackend.saveState(stackName, newState);
+      const newEtag = await this.stateBackend.saveState(stackName, this.stackRegion, newState);
       this.logger.debug(`State saved (ETag: ${newEtag})`);
       const durationMs = Date.now() - startTime;
       const unchangedCount = this.diffCalculator.filterByType(changes, "NO_CHANGE").length + actualCounts.skipped;
@@ -26392,7 +26656,7 @@ var DeployEngine = class {
       renderer.stop();
       process.removeListener("SIGINT", sigintHandler);
       try {
-        await this.lockManager.releaseLock(stackName);
+        await this.lockManager.releaseLock(stackName, this.stackRegion);
         this.logger.debug("Lock released");
       } catch (lockError) {
         this.logger.warn(
@@ -26410,11 +26674,12 @@ var DeployEngine = class {
    * - DELETE follows reverse dependency order (a node starts as soon as all
    *   resources that depend ON it have finished deleting)
    */
-  async executeDeployment(template, currentState, changes, dag, executionLevels, stackName, parameterValues, conditions, currentEtag, progress) {
+  async executeDeployment(template, currentState, changes, dag, executionLevels, stackName, parameterValues, conditions, currentEtag, progress, migrationPending = false) {
     const concurrency = this.options.concurrency;
     const newResources = { ...currentState.resources };
     const actualCounts = { created: 0, updated: 0, deleted: 0, skipped: 0 };
     const completedOperations = [];
+    let pendingMigration = migrationPending;
     let saveChain = Promise.resolve();
     const saveStateAfterResource = (logicalId) => {
       if (currentEtag === void 0)
@@ -26422,14 +26687,23 @@ var DeployEngine = class {
       saveChain = saveChain.then(async () => {
         try {
           const partialState = {
-            version: 1,
-            ...this.stackRegion && { region: this.stackRegion },
+            version: STATE_SCHEMA_VERSION_CURRENT,
+            region: this.stackRegion,
             stackName: currentState.stackName,
             resources: newResources,
             outputs: currentState.outputs,
             lastModified: Date.now()
           };
-          currentEtag = await this.stateBackend.saveState(stackName, partialState, currentEtag);
+          const migrate = pendingMigration;
+          const expectedEtag = migrate ? void 0 : currentEtag;
+          currentEtag = await this.stateBackend.saveState(
+            stackName,
+            this.stackRegion,
+            partialState,
+            { ...expectedEtag !== void 0 && { expectedEtag }, migrateLegacy: migrate }
+          );
+          if (migrate)
+            pendingMigration = false;
           this.logger.debug(`State saved after ${logicalId}`);
         } catch (error) {
           this.logger.warn(
@@ -26563,14 +26837,23 @@ var DeployEngine = class {
     } catch (error) {
       try {
         const preRollbackState = {
-          version: 1,
-          ...this.stackRegion && { region: this.stackRegion },
+          version: STATE_SCHEMA_VERSION_CURRENT,
+          region: this.stackRegion,
           stackName: currentState.stackName,
           resources: newResources,
           outputs: currentState.outputs,
           lastModified: Date.now()
         };
-        currentEtag = await this.stateBackend.saveState(stackName, preRollbackState, currentEtag);
+        const migrate = pendingMigration;
+        const expectedEtag = migrate ? void 0 : currentEtag;
+        currentEtag = await this.stateBackend.saveState(
+          stackName,
+          this.stackRegion,
+          preRollbackState,
+          { ...expectedEtag !== void 0 && { expectedEtag }, migrateLegacy: migrate }
+        );
+        if (migrate)
+          pendingMigration = false;
         this.logger.debug("Partial state saved before rollback (orphaned resource tracking)");
       } catch (saveError) {
         this.logger.warn(
@@ -26591,31 +26874,35 @@ var DeployEngine = class {
       }
       try {
         const postRollbackState = {
-          version: 1,
-          ...this.stackRegion && { region: this.stackRegion },
+          version: STATE_SCHEMA_VERSION_CURRENT,
+          region: this.stackRegion,
           stackName: currentState.stackName,
           resources: newResources,
           outputs: currentState.outputs,
           lastModified: Date.now()
         };
-        await this.stateBackend.saveState(stackName, postRollbackState, currentEtag);
+        await this.stateBackend.saveState(stackName, this.stackRegion, postRollbackState, {
+          ...currentEtag !== void 0 && { expectedEtag: currentEtag }
+        });
         this.logger.debug("State saved after deployment failure");
       } catch (saveError) {
         this.logger.debug(
           `Retrying state save after rollback (ETag mismatch): ${saveError instanceof Error ? saveError.message : String(saveError)}`
         );
         try {
-          const freshState = await this.stateBackend.getState(stackName);
+          const freshState = await this.stateBackend.getState(stackName, this.stackRegion);
           const freshEtag = freshState?.etag;
           const postRollbackState = {
-            version: 1,
-            ...this.stackRegion && { region: this.stackRegion },
+            version: STATE_SCHEMA_VERSION_CURRENT,
+            region: this.stackRegion,
             stackName: currentState.stackName,
             resources: newResources,
             outputs: currentState.outputs,
             lastModified: Date.now()
           };
-          await this.stateBackend.saveState(stackName, postRollbackState, freshEtag);
+          await this.stateBackend.saveState(stackName, this.stackRegion, postRollbackState, {
+            ...freshEtag !== void 0 && { expectedEtag: freshEtag }
+          });
           this.logger.debug("State saved after deployment failure (retry succeeded)");
         } catch (retryError) {
           this.logger.warn(
@@ -26634,8 +26921,8 @@ var DeployEngine = class {
     );
     return {
       state: {
-        version: 1,
-        ...this.stackRegion && { region: this.stackRegion },
+        version: STATE_SCHEMA_VERSION_CURRENT,
+        region: this.stackRegion,
         stackName: currentState.stackName,
         resources: newResources,
         outputs,
@@ -27642,19 +27929,18 @@ async function diffCommand(stacks, options) {
       logger.info(`
 Calculating diff for stack: ${stackInfo.stackName}`);
       const template = stackInfo.template;
-      let currentState;
-      const stateResult = await stateBackend.getState(stackInfo.stackName);
-      if (stateResult) {
-        currentState = stateResult.state;
-      } else {
-        logger.debug(`No existing state for ${stackInfo.stackName}`);
-        currentState = {
-          stackName: stackInfo.stackName,
-          resources: {},
-          outputs: {},
-          version: 1,
-          lastModified: Date.now()
-        };
+      const stackRegion = stackInfo.region || region;
+      const stateResult = await stateBackend.getState(stackInfo.stackName, stackRegion);
+      const currentState = stateResult ? stateResult.state : {
+        stackName: stackInfo.stackName,
+        region: stackRegion,
+        resources: {},
+        outputs: {},
+        version: STATE_SCHEMA_VERSION_CURRENT,
+        lastModified: Date.now()
+      };
+      if (!stateResult) {
+        logger.debug(`No existing state for ${stackInfo.stackName} (${stackRegion})`);
       }
       const diffResolveFn = (value) => intrinsicResolver.resolve(value, {
         template,
@@ -27776,19 +28062,27 @@ async function destroyCommand(stackArgs, options) {
         });
         appStacks = result.stacks.map((s) => ({
           stackName: s.stackName,
-          displayName: s.displayName
+          displayName: s.displayName,
+          ...s.region && { region: s.region }
         }));
       } catch {
         logger.debug("Could not synthesize app, falling back to state-based stack list");
       }
     }
-    const allStateStacks = await stateBackend.listStacks();
+    const allStateRefs = await stateBackend.listStacks();
     let candidateStacks;
     if (appStacks.length > 0) {
-      const stateSet = new Set(allStateStacks);
-      candidateStacks = appStacks.filter((s) => stateSet.has(s.stackName));
+      const stateNames = new Set(allStateRefs.map((r) => r.stackName));
+      candidateStacks = appStacks.filter((s) => stateNames.has(s.stackName));
     } else if (stackArgs.length > 0 || options.stack || options.all) {
-      candidateStacks = allStateStacks.map((name) => ({ stackName: name }));
+      const seen = /* @__PURE__ */ new Set();
+      candidateStacks = [];
+      for (const ref of allStateRefs) {
+        if (seen.has(ref.stackName))
+          continue;
+        seen.add(ref.stackName);
+        candidateStacks.push({ stackName: ref.stackName });
+      }
     } else {
       throw new Error(
         "Could not determine which stacks belong to this app. Specify stack names explicitly, use --all, or ensure --app / cdk.json is configured."
@@ -27815,10 +28109,38 @@ async function destroyCommand(stackArgs, options) {
       return;
     }
     logger.info(`Found ${stackNames.length} stack(s) to destroy: ${stackNames.join(", ")}`);
+    const stateRefsByName = /* @__PURE__ */ new Map();
+    for (const ref of allStateRefs) {
+      const arr = stateRefsByName.get(ref.stackName) ?? [];
+      arr.push(ref);
+      stateRefsByName.set(ref.stackName, arr);
+    }
     for (const stackName of stackNames) {
       logger.info(`
 Preparing to destroy stack: ${stackName}`);
-      const stateResult = await stateBackend.getState(stackName);
+      const refs = stateRefsByName.get(stackName) ?? [];
+      const synthStack = appStacks.find((s) => s.stackName === stackName);
+      const synthRegion = synthStack?.region;
+      let stackTargetRegion;
+      if (refs.length === 0) {
+        logger.warn(`No state found for stack ${stackName}, skipping`);
+        continue;
+      } else if (refs.length === 1) {
+        const onlyRegion = refs[0]?.region;
+        if (!onlyRegion) {
+          stackTargetRegion = region;
+        } else {
+          stackTargetRegion = onlyRegion;
+        }
+      } else if (synthRegion && refs.some((r) => r.region === synthRegion)) {
+        stackTargetRegion = synthRegion;
+      } else {
+        const regions = refs.map((r) => r.region ?? "(legacy)").join(", ");
+        throw new Error(
+          `Stack '${stackName}' has state in multiple regions: ${regions}. Use 'cdkd state rm ${stackName} --region <region>' to remove cdkd's record for one region, or run destroy from a CDK app whose env.region matches one of them.`
+        );
+      }
+      const stateResult = await stateBackend.getState(stackName, stackTargetRegion);
       if (!stateResult) {
         logger.warn(`No state found for stack ${stackName}, skipping`);
         continue;
@@ -27827,7 +28149,7 @@ Preparing to destroy stack: ${stackName}`);
       const resourceCount = Object.keys(currentState.resources).length;
       if (resourceCount === 0) {
         logger.info(`Stack ${stackName} has no resources, cleaning up state...`);
-        await stateBackend.deleteState(stackName);
+        await stateBackend.deleteState(stackName, stackTargetRegion);
         logger.info("\u2713 State deleted");
         continue;
       }
@@ -27852,7 +28174,7 @@ Are you sure you want to destroy stack "${stackName}" and delete all ${resourceC
           continue;
         }
       }
-      const stackRegion = currentState.region;
+      const stackRegion = stackTargetRegion;
       let destroyProviderRegistry = providerRegistry;
       let destroyAwsClients;
       if (stackRegion && stackRegion !== region) {
@@ -27870,7 +28192,7 @@ Are you sure you want to destroy stack "${stackName}" and delete all ${resourceC
       }
       logger.info(`
 Acquiring lock for stack ${stackName}...`);
-      await lockManager.acquireLock(stackName, "destroy");
+      await lockManager.acquireLock(stackName, stackRegion, void 0, "destroy");
       const renderer = getLiveRenderer();
       renderer.start();
       try {
@@ -27985,7 +28307,7 @@ Acquiring lock for stack ${stackName}...`);
           await Promise.all(deletePromises);
         }
         if (errorCount === 0) {
-          await stateBackend.deleteState(stackName);
+          await stateBackend.deleteState(stackName, stackRegion);
           logger.debug("State deleted");
         } else {
           logger.warn(`${errorCount} resource(s) failed to delete. State preserved.`);
@@ -27997,7 +28319,7 @@ Acquiring lock for stack ${stackName}...`);
       } finally {
         renderer.stop();
         logger.debug("Releasing lock...");
-        await lockManager.releaseLock(stackName);
+        await lockManager.releaseLock(stackName, stackRegion);
         if (destroyAwsClients) {
           destroyAwsClients.destroy();
           process.env["AWS_REGION"] = region;
@@ -28058,7 +28380,7 @@ function createPublishAssetsCommand() {
 }
 
 // src/cli/commands/force-unlock.ts
-import { Command as Command8 } from "commander";
+import { Command as Command8, Option as Option3 } from "commander";
 init_aws_clients();
 async function forceUnlockCommand(stackArgs, options) {
   const logger = getLogger();
@@ -28082,17 +28404,33 @@ async function forceUnlockCommand(stackArgs, options) {
       prefix: options.statePrefix
     };
     const lockManager = new LockManager(awsClients.s3, stateConfig);
+    const stateBackend = new S3StateBackend(awsClients.s3, stateConfig);
     for (const stackName of stackPatterns) {
-      logger.info(`Force-unlocking stack: ${stackName}`);
-      try {
-        await lockManager.forceReleaseLock(stackName);
-        logger.info(`\u2713 Lock released for stack: ${stackName}`);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("No lock found") || message.includes("NoSuchKey")) {
-          logger.info(`No lock found for stack: ${stackName}`);
+      let regionsToTry;
+      if (options.stackRegion) {
+        regionsToTry = [options.stackRegion];
+      } else {
+        const refs = await stateBackend.listStacks();
+        const matched = refs.filter((r) => r.stackName === stackName);
+        if (matched.length === 0) {
+          regionsToTry = [region];
         } else {
-          logger.error(`Failed to unlock stack ${stackName}: ${message}`);
+          regionsToTry = matched.map((r) => r.region);
+        }
+      }
+      for (const r of regionsToTry) {
+        const where = r ? `${stackName} (${r})` : `${stackName} (legacy lock key)`;
+        logger.info(`Force-unlocking stack: ${where}`);
+        try {
+          await lockManager.forceReleaseLock(stackName, r);
+          logger.info(`\u2713 Lock released for stack: ${where}`);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.includes("No lock found") || message.includes("NoSuchKey")) {
+            logger.info(`No lock found for stack: ${where}`);
+          } else {
+            logger.error(`Failed to unlock stack ${where}: ${message}`);
+          }
         }
       }
     }
@@ -28101,15 +28439,47 @@ async function forceUnlockCommand(stackArgs, options) {
   }
 }
 function createForceUnlockCommand() {
-  const cmd = new Command8("force-unlock").description("Force-release a stale lock on a stack").argument("[stacks...]", "Stack name(s) to unlock").action(withErrorHandling(forceUnlockCommand));
+  const cmd = new Command8("force-unlock").description("Force-release a stale lock on a stack").argument("[stacks...]", "Stack name(s) to unlock").addOption(
+    new Option3(
+      "--stack-region <region>",
+      "Stack region whose lock to release (use when the same stack name has locks in multiple regions). Defaults to all regions where the stack has state."
+    )
+  ).action(withErrorHandling(forceUnlockCommand));
   [...commonOptions, ...stateOptions, ...stackOptions].forEach((opt) => cmd.addOption(opt));
   return cmd;
 }
 
 // src/cli/commands/state.ts
 import * as readline2 from "node:readline/promises";
-import { Command as Command9 } from "commander";
+import { Command as Command9, Option as Option4 } from "commander";
 init_aws_clients();
+function formatStackRef(ref) {
+  return ref.region ? `${ref.stackName} (${ref.region})` : ref.stackName;
+}
+function resolveSingleRegion(stackName, refs, requestedRegion) {
+  const matches = refs.filter((r) => r.stackName === stackName);
+  if (matches.length === 0) {
+    throw new Error(
+      `No state found for stack '${stackName}'. Run 'cdkd state list' to see available stacks.`
+    );
+  }
+  if (requestedRegion) {
+    const ref = matches.find((r) => r.region === requestedRegion);
+    if (!ref) {
+      const seen = matches.map((r) => r.region ?? "(legacy)").join(", ");
+      throw new Error(
+        `No state found for stack '${stackName}' in region '${requestedRegion}'. Available regions: ${seen}.`
+      );
+    }
+    return ref;
+  }
+  if (matches.length === 1)
+    return matches[0];
+  const regions = matches.map((r) => r.region ?? "(legacy)").join(", ");
+  throw new Error(
+    `Stack '${stackName}' has state in multiple regions: ${regions}. Re-run with --region <region> to disambiguate.`
+  );
+}
 async function setupStateBackend(options) {
   const awsClients = new AwsClients({
     ...options.region && { region: options.region },
@@ -28131,34 +28501,52 @@ async function setupStateBackend(options) {
     dispose: () => awsClients.destroy()
   };
 }
+function sortRefs(refs) {
+  return refs.slice().sort((a, b) => {
+    if (a.stackName < b.stackName)
+      return -1;
+    if (a.stackName > b.stackName)
+      return 1;
+    const ar = a.region ?? "\uFFFF";
+    const br = b.region ?? "\uFFFF";
+    if (ar < br)
+      return -1;
+    if (ar > br)
+      return 1;
+    return 0;
+  });
+}
 async function stateListCommand(options) {
   const logger = getLogger();
   if (options.verbose)
     logger.setLevel("debug");
   const setup = await setupStateBackend(options);
   try {
-    const stackNames = (await setup.stateBackend.listStacks()).slice().sort();
+    const refs = sortRefs(await setup.stateBackend.listStacks());
     if (!options.long && !options.json) {
-      for (const name of stackNames) {
-        process.stdout.write(`${name}
+      for (const ref of refs) {
+        process.stdout.write(`${formatStackRef(ref)}
 `);
       }
       return;
     }
     if (options.json && !options.long) {
-      process.stdout.write(`${JSON.stringify(stackNames, null, 2)}
+      const payload = refs.map((r) => ({ stackName: r.stackName, region: r.region ?? null }));
+      process.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
       return;
     }
     const details = await Promise.all(
-      stackNames.map(async (stackName) => {
+      refs.map(async (ref) => {
+        const lookupRegion = ref.region ?? "";
         const [stateResult, locked] = await Promise.all([
-          setup.stateBackend.getState(stackName),
-          setup.lockManager.isLocked(stackName)
+          lookupRegion ? setup.stateBackend.getState(ref.stackName, lookupRegion) : Promise.resolve(null),
+          setup.lockManager.isLocked(ref.stackName, ref.region)
         ]);
         const state = stateResult?.state;
         return {
-          stackName,
+          stackName: ref.stackName,
+          region: ref.region ?? null,
           resourceCount: state ? Object.keys(state.resources).length : 0,
           lastModified: state && typeof state.lastModified === "number" ? new Date(state.lastModified).toISOString() : null,
           locked
@@ -28172,7 +28560,13 @@ async function stateListCommand(options) {
     }
     const lines = [];
     for (const detail of details) {
-      lines.push(detail.stackName);
+      lines.push(
+        formatStackRef({
+          stackName: detail.stackName,
+          ...detail.region ? { region: detail.region } : {}
+        })
+      );
+      lines.push(`  Region: ${detail.region ?? "(legacy)"}`);
       lines.push(`  Resources: ${detail.resourceCount}`);
       lines.push(`  Last Modified: ${detail.lastModified ?? "unknown"}`);
       lines.push(`  Lock: ${detail.locked ? "locked" : "unlocked"}`);
@@ -28200,10 +28594,17 @@ async function stateResourcesCommand(stackName, options) {
     logger.setLevel("debug");
   const setup = await setupStateBackend(options);
   try {
-    const stateResult = await setup.stateBackend.getState(stackName);
+    const refs = await setup.stateBackend.listStacks();
+    const ref = resolveSingleRegion(stackName, refs, options.stackRegion);
+    if (!ref.region) {
+      throw new Error(
+        `Stack '${stackName}' has only a legacy state record without a region. Run 'cdkd deploy ${stackName}' (or any cdkd write) to migrate it to the region-scoped layout, then re-run this command.`
+      );
+    }
+    const stateResult = await setup.stateBackend.getState(stackName, ref.region);
     if (!stateResult) {
       throw new Error(
-        `No state found for stack '${stackName}' in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
+        `No state found for stack '${stackName}' (${ref.region}) in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
       );
     }
     const resources = stateResult.state.resources ?? {};
@@ -28286,7 +28687,7 @@ function formatLockSummary(lockInfo) {
   return `locked by ${lockInfo.owner}${opStr}, ${expiresStr}`;
 }
 function createStateResourcesCommand() {
-  const cmd = new Command9("resources").description("List resources recorded in a stack's state").argument("<stack>", "Stack name (physical CloudFormation name)").option("-l, --long", "Include dependencies and attributes per resource", false).option("--json", "Output as JSON", false).action(withErrorHandling(stateResourcesCommand));
+  const cmd = new Command9("resources").description("List resources recorded in a stack's state").argument("<stack>", "Stack name (physical CloudFormation name)").option("-l, --long", "Include dependencies and attributes per resource", false).option("--json", "Output as JSON", false).addOption(stackRegionOption()).action(withErrorHandling(stateResourcesCommand));
   [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
   return cmd;
 }
@@ -28296,13 +28697,20 @@ async function stateShowCommand(stackName, options) {
     logger.setLevel("debug");
   const setup = await setupStateBackend(options);
   try {
+    const refs = await setup.stateBackend.listStacks();
+    const ref = resolveSingleRegion(stackName, refs, options.stackRegion);
+    if (!ref.region) {
+      throw new Error(
+        `Stack '${stackName}' has only a legacy state record without a region. Run 'cdkd deploy ${stackName}' (or any cdkd write) to migrate it to the region-scoped layout, then re-run this command.`
+      );
+    }
     const [stateResult, lockInfo] = await Promise.all([
-      setup.stateBackend.getState(stackName),
-      setup.lockManager.getLockInfo(stackName)
+      setup.stateBackend.getState(stackName, ref.region),
+      setup.lockManager.getLockInfo(stackName, ref.region)
     ]);
     if (!stateResult) {
       throw new Error(
-        `No state found for stack '${stackName}' in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
+        `No state found for stack '${stackName}' (${ref.region}) in s3://${setup.bucket}/${setup.prefix}/. Run 'cdkd state list' to see available stacks.`
       );
     }
     if (options.json) {
@@ -28366,7 +28774,7 @@ async function stateShowCommand(stackName, options) {
   }
 }
 function createStateShowCommand() {
-  const cmd = new Command9("show").description("Show the full cdkd state record for a stack (metadata, outputs, resources)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--json", "Output the raw state and lock as JSON", false).action(withErrorHandling(stateShowCommand));
+  const cmd = new Command9("show").description("Show the full cdkd state record for a stack (metadata, outputs, resources)").argument("<stack>", "Stack name (physical CloudFormation name)").option("--json", "Output the raw state and lock as JSON", false).addOption(stackRegionOption()).action(withErrorHandling(stateShowCommand));
   [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
   return cmd;
 }
@@ -28379,24 +28787,36 @@ async function stateRmCommand(stackArgs, options) {
   }
   const setup = await setupStateBackend(options);
   try {
+    const refs = await setup.stateBackend.listStacks();
     for (const stackName of stackArgs) {
-      const exists = await setup.stateBackend.stateExists(stackName);
-      if (!exists) {
+      const stackRefs = refs.filter((r) => r.stackName === stackName);
+      if (stackRefs.length === 0) {
         logger.info(`No state found for stack: ${stackName}, skipping`);
         continue;
       }
+      const targets = options.stackRegion ? stackRefs.filter((r) => r.region === options.stackRegion) : stackRefs;
+      if (targets.length === 0) {
+        const seen = stackRefs.map((r) => r.region ?? "(legacy)").join(", ");
+        throw new Error(
+          `No state found for stack '${stackName}' in region '${options.stackRegion}'. Available regions: ${seen}.`
+        );
+      }
       if (!options.force) {
-        const locked = await setup.lockManager.isLocked(stackName);
-        if (locked) {
-          throw new Error(
-            `Stack '${stackName}' is locked. Run 'cdkd force-unlock ${stackName}' first, or pass --force to remove anyway.`
-          );
+        for (const target of targets) {
+          const locked = await setup.lockManager.isLocked(stackName, target.region);
+          if (locked) {
+            const where = target.region ?? "(legacy)";
+            throw new Error(
+              `Stack '${stackName}' (${where}) is locked. Run 'cdkd force-unlock ${stackName}${target.region ? ` --stack-region ${target.region}` : ""}' first, or pass --force to remove anyway.`
+            );
+          }
         }
       }
       if (!options.yes && !options.force) {
+        const targetList = targets.map((t) => formatStackRef(t)).join(", ");
         process.stdout.write(
           `
-WARNING: This removes cdkd's state record for '${stackName}' only. AWS resources will NOT be deleted.
+WARNING: This removes cdkd's state record for [${targetList}] only. AWS resources will NOT be deleted.
 Use 'cdkd destroy ${stackName}' if you want to delete the actual resources.
 
 `
@@ -28406,7 +28826,7 @@ Use 'cdkd destroy ${stackName}' if you want to delete the actual resources.
           output: process.stdout
         });
         const answer = await rl.question(
-          `Remove state for stack '${stackName}' from s3://${setup.bucket}/${setup.prefix}/? (y/N): `
+          `Remove state for ${targetList} from s3://${setup.bucket}/${setup.prefix}/? (y/N): `
         );
         rl.close();
         const trimmed = answer.trim().toLowerCase();
@@ -28415,16 +28835,28 @@ Use 'cdkd destroy ${stackName}' if you want to delete the actual resources.
           continue;
         }
       }
-      await setup.stateBackend.deleteState(stackName);
-      await setup.lockManager.forceReleaseLock(stackName);
-      logger.info(`\u2713 Removed state for stack: ${stackName}`);
+      for (const target of targets) {
+        if (target.region) {
+          await setup.stateBackend.deleteState(stackName, target.region);
+          await setup.lockManager.forceReleaseLock(stackName, target.region);
+        } else {
+          await setup.lockManager.forceReleaseLock(stackName, void 0);
+        }
+        logger.info(`\u2713 Removed state for stack: ${formatStackRef(target)}`);
+      }
     }
   } finally {
     setup.dispose();
   }
 }
+function stackRegionOption() {
+  return new Option4(
+    "--stack-region <region>",
+    "Region of the stack record to operate on. Required when the same stack name has state in multiple regions."
+  );
+}
 function createStateRmCommand() {
-  const cmd = new Command9("rm").description("Remove cdkd state for one or more stacks (does NOT delete AWS resources)").argument("<stacks...>", "Stack name(s) to remove from state").option("-f, --force", "Skip confirmation and remove even if the stack is locked", false).action(withErrorHandling(stateRmCommand));
+  const cmd = new Command9("rm").description("Remove cdkd state for one or more stacks (does NOT delete AWS resources)").argument("<stacks...>", "Stack name(s) to remove from state").option("-f, --force", "Skip confirmation and remove even if the stack is locked", false).addOption(stackRegionOption()).action(withErrorHandling(stateRmCommand));
   [...commonOptions, ...stateOptions].forEach((opt) => cmd.addOption(opt));
   return cmd;
 }
@@ -28462,7 +28894,7 @@ function reorderArgs(argv) {
 }
 async function main() {
   const program = new Command10();
-  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.7.0");
+  program.name("cdkd").description("CDK Direct - Deploy AWS CDK apps directly via SDK/Cloud Control API").version("0.8.0");
   program.addCommand(createBootstrapCommand());
   program.addCommand(createSynthCommand());
   program.addCommand(createListCommand());