@go-to-k/cdkd 0.6.0 → 0.8.0

package/dist/index.js

@@ -2661,6 +2661,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;
@@ -2668,9 +2676,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`;
   }
   /**
@@ -2696,101 +2711,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.
    *
-   * Note: S3 returns ETag with surrounding quotes (e.g., "abc123").
-   * We preserve the quotes as they are required for IfMatch conditions.
+   * 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.
+   *
+   * 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") {
@@ -2799,63 +2856,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 ListObjectsV2Command({
+        new GetObjectCommand({
           Bucket: this.config.bucket,
-          Prefix: `${this.config.prefix}/`,
-          Delimiter: "/"
+          Key: this.getLegacyStateKey(stackName)
         })
       );
-      if (!response.CommonPrefixes) {
-        return [];
-      }
-      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;
+      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 GetObjectCommand({
+          Bucket: this.config.bucket,
+          Key: this.getLegacyStateKey(stackName)
+        })
+      );
+      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;
+      }
+      return { state, etag: response.ETag };
+    } catch (error) {
+      if (isNoSuchKey(error))
+        return null;
+      throw new StateError(
+        `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(
-        `Failed to list stacks: ${error instanceof Error ? error.message : String(error)}`,
+        `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 {
@@ -2876,10 +3100,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
@@ -2918,11 +3156,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 = {
@@ -2932,7 +3171,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({
@@ -2945,17 +3184,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(
@@ -2969,13 +3208,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;
             }
@@ -2985,16 +3224,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(
@@ -3032,27 +3275,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
       );
     }
@@ -3062,23 +3305,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,
@@ -3099,28 +3347,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.")
     );
   }
 };
@@ -4903,35 +5151,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.`
     );
   }
   /**
@@ -7478,7 +7736,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
@@ -7487,7 +7749,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;
@@ -7501,16 +7763,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`
       );
@@ -7596,9 +7859,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;
@@ -7614,7 +7878,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(
@@ -7632,11 +7896,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)
@@ -7644,14 +7909,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(
@@ -7785,14 +8059,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(
@@ -7813,31 +8096,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(
@@ -7856,8 +8143,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,