@quadnix/octo 0.1.0 → 0.2.0

package/dist/services/state-management/terraform-state.service.d.ts

@@ -16,6 +16,7 @@ import { StateManagementService } from './state-management.service.js';
  */
 export declare class TerraformStateService {
     private checkInQueue;
+    private isPeriodicCheckInRunning;
     private periodicCheckIn;
     private readonly stateManagementService;
     /**
@@ -23,11 +24,13 @@ export declare class TerraformStateService {
      */
     constructor(stateManagementService: StateManagementService);
     /**
-     * Writes every module folder's terraform state to the state provider.
+     * Writes every module folder's terraform state to the state provider, as one change.
      *
      * A folder holding no state file, or one recording no resources, has its state **deleted** rather
      * than written - that is a module terraform has destroyed, and a file recording nothing is a file
-     * worth nobody's history.
+     * worth nobody's history. A file that does not parse is left out, keeping the provider's copy:
+     * terraform rewrites the file in place, so a check-in during a command can read it empty or half
+     * written.
      *
      * Check-ins are serialized, so the one on a command's return never races the one on the timer.
      */
@@ -36,23 +39,43 @@ export declare class TerraformStateService {
      * Writes the state provider's terraform state into every module folder.
      *
      * A module the provider holds nothing for keeps whatever its folder already has, which is what
-     * adopts the state of a stack that ran with a local backend until now. The check-in that follows
-     * hands that state to the provider, and from then on the provider is the one that answers.
+     * adopts the state of a stack that ran with a local backend until now. A folder whose state is
+     * ahead of the provider's keeps it too, which is what a run killed before its last check-in
+     * leaves behind. The check-in that follows hands either to the provider.
      */
     checkOut(terragruntDir: string, moduleIds: string[]): Promise<void>;
     /**
-     * Starts checking state in on a timer, bounding what a killed runner loses to one interval.
+     * The state moves the last generate recorded, each from one module folder into another.
      */
-    startPeriodicCheckIn(terragruntDir: string, moduleIds: string[]): void;
+    getRecordedMoves(): Promise<{
+        addresses: {
+            from: string;
+            to: string;
+        }[];
+        fromModuleId: string;
+        moduleId: string;
+        outputs: {
+            from: string;
+            to: string;
+        }[];
+    }[]>;
+    /**
+     * Starts checking state in every `intervalInMs`, bounding what a killed runner loses to one interval.
+     */
+    startPeriodicCheckIn(terragruntDir: string, moduleIds: string[], intervalInMs: number): void;
     /**
      * Stops the timer {@link TerraformStateService.startPeriodicCheckIn} started.
      */
     stopPeriodicCheckIn(): void;
     /**
-     * Whether a terraform state file records nothing, which is what a destroyed module is left with.
-     * State that cannot be parsed is treated as holding resources, so an unreadable file is kept.
+     * Whether the folder's terraform state is a later write of the same state the provider holds: the
+     * same `lineage`, and a higher `serial`. State that cannot be read or parsed is never ahead.
+     */
+    private isFolderStateAhead;
+    /**
+     * A terraform state file's contents, or `undefined` when it does not parse.
      */
-    private holdsNoResources;
+    private parseState;
     /**
      * The name one module's terraform state is stored under, alongside Octo's own state files.
      */

package/dist/services/state-management/terraform-state.service.js

@@ -10,7 +10,6 @@ import { join } from 'node:path';
 import { Factory } from '../../decorators/factory.decorator.js';
 import { Container } from '../../functions/container/container.js';
 import { StateManagementService } from './state-management.service.js';
-const CHECK_IN_INTERVAL_IN_MS = 60 * 1000;
 const TERRAFORM_STATE_FILE_NAME = 'terraform.tfstate';
 /**
  * Moves each module folder's `terraform.tfstate` in and out of Octo's {@link IStateProvider}.
@@ -33,14 +32,17 @@ export class TerraformStateService {
      */
     constructor(stateManagementService) {
         this.checkInQueue = Promise.resolve();
+        this.isPeriodicCheckInRunning = false;
         this.stateManagementService = stateManagementService;
     }
     /**
-     * Writes every module folder's terraform state to the state provider.
+     * Writes every module folder's terraform state to the state provider, as one change.
      *
      * A folder holding no state file, or one recording no resources, has its state **deleted** rather
      * than written - that is a module terraform has destroyed, and a file recording nothing is a file
-     * worth nobody's history.
+     * worth nobody's history. A file that does not parse is left out, keeping the provider's copy:
+     * terraform rewrites the file in place, so a check-in during a command can read it empty or half
+     * written.
      *
      * Check-ins are serialized, so the one on a command's return never races the one on the timer.
      */
@@ -52,8 +54,9 @@ export class TerraformStateService {
      * Writes the state provider's terraform state into every module folder.
      *
      * A module the provider holds nothing for keeps whatever its folder already has, which is what
-     * adopts the state of a stack that ran with a local backend until now. The check-in that follows
-     * hands that state to the provider, and from then on the provider is the one that answers.
+     * adopts the state of a stack that ran with a local backend until now. A folder whose state is
+     * ahead of the provider's keeps it too, which is what a run killed before its last check-in
+     * leaves behind. The check-in that follows hands either to the provider.
      */
     async checkOut(terragruntDir, moduleIds) {
         for (const moduleId of moduleIds) {
@@ -67,21 +70,41 @@ export class TerraformStateService {
                 }
                 throw error;
             }
-            await writeFile(join(terragruntDir, moduleId, TERRAFORM_STATE_FILE_NAME), data);
+            const stateFilePath = join(terragruntDir, moduleId, TERRAFORM_STATE_FILE_NAME);
+            if (await this.isFolderStateAhead(stateFilePath, data)) {
+                continue;
+            }
+            await writeFile(stateFilePath, data);
         }
     }
     /**
-     * Starts checking state in on a timer, bounding what a killed runner loses to one interval.
+     * The state moves the last generate recorded, each from one module folder into another.
+     */
+    async getRecordedMoves() {
+        const { userData } = await this.stateManagementService.getModelState(this.stateManagementService.modelStateFileName);
+        return (userData.terraformFolders ?? []).flatMap(({ moduleId, moves = [] }) => moves.map(({ addresses, fromModuleId, outputs }) => ({ addresses, fromModuleId, moduleId, outputs })));
+    }
+    /**
+     * Starts checking state in every `intervalInMs`, bounding what a killed runner loses to one interval.
      */
-    startPeriodicCheckIn(terragruntDir, moduleIds) {
+    startPeriodicCheckIn(terragruntDir, moduleIds, intervalInMs) {
         if (this.periodicCheckIn) {
             return;
         }
         this.periodicCheckIn = setInterval(() => {
+            // Skip the tick while the last one is still checking in, rather than waiting behind it.
+            if (this.isPeriodicCheckInRunning) {
+                return;
+            }
+            this.isPeriodicCheckInRunning = true;
             // A tick that fails is not worth aborting the terraform command that is still running - the
             // check-in on its return reports the failure instead.
-            void this.checkIn(terragruntDir, moduleIds).catch(() => { });
-        }, CHECK_IN_INTERVAL_IN_MS);
+            void this.checkIn(terragruntDir, moduleIds)
+                .catch(() => { })
+                .finally(() => {
+                this.isPeriodicCheckInRunning = false;
+            });
+        }, intervalInMs);
     }
     /**
      * Stops the timer {@link TerraformStateService.startPeriodicCheckIn} started.
@@ -93,18 +116,33 @@ export class TerraformStateService {
         }
     }
     /**
-     * Whether a terraform state file records nothing, which is what a destroyed module is left with.
-     * State that cannot be parsed is treated as holding resources, so an unreadable file is kept.
+     * Whether the folder's terraform state is a later write of the same state the provider holds: the
+     * same `lineage`, and a higher `serial`. State that cannot be read or parsed is never ahead.
      */
-    holdsNoResources(data) {
+    async isFolderStateAhead(stateFilePath, providerData) {
         try {
-            const state = JSON.parse(data.toString());
-            return Array.isArray(state.resources) && state.resources.length === 0;
+            const folderState = JSON.parse(await readFile(stateFilePath, 'utf-8'));
+            const providerState = JSON.parse(providerData.toString());
+            return (typeof folderState.serial === 'number' &&
+                typeof providerState.serial === 'number' &&
+                folderState.lineage === providerState.lineage &&
+                folderState.serial > providerState.serial);
         }
         catch {
             return false;
         }
     }
+    /**
+     * A terraform state file's contents, or `undefined` when it does not parse.
+     */
+    parseState(data) {
+        try {
+            return JSON.parse(data.toString());
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * The name one module's terraform state is stored under, alongside Octo's own state files.
      */
@@ -115,21 +153,26 @@ export class TerraformStateService {
      * The body of a check-in, run one at a time through {@link TerraformStateService.checkIn}.
      */
     async writeStates(terragruntDir, moduleIds) {
+        const stateFiles = [];
         for (const moduleId of moduleIds) {
             const stateFilePath = join(terragruntDir, moduleId, TERRAFORM_STATE_FILE_NAME);
             const stateFileName = this.stateFileName(moduleId);
+            // Delete the state of a module with no state file.
             if (!existsSync(stateFilePath)) {
-                await this.stateManagementService.deleteState(stateFileName);
+                stateFiles.push({ data: undefined, stateFileName });
                 continue;
             }
+            // Skip a file terraform is still writing.
             const data = await readFile(stateFilePath);
-            if (this.holdsNoResources(data)) {
-                await this.stateManagementService.deleteState(stateFileName);
-            }
-            else {
-                await this.stateManagementService.saveState(stateFileName, data);
+            const state = this.parseState(data);
+            if (!state) {
+                continue;
             }
+            // Delete the state of a module recording no resources, and write every other.
+            const holdsNoResources = Array.isArray(state.resources) && state.resources.length === 0;
+            stateFiles.push({ data: holdsNoResources ? undefined : data, stateFileName });
         }
+        await this.stateManagementService.saveStates(stateFiles);
     }
 }
 /**

package/dist/services/state-management/terraform-state.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"terraform-state.service.js","sourceRoot":"","sources":["../../../src/services/state-management/terraform-state.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"terraform-state.service.js","sourceRoot":"","sources":["../../../src/services/state-management/terraform-state.service.ts"],"names":[],"mappings":"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"}

package/dist/services/state-management/test.state-provider.d.ts

@@ -9,10 +9,6 @@ import type { IStateProvider } from './state-provider.interface.js';
 export declare class TestStateProvider implements IStateProvider {
     private readonly localState;
     private lockId;
-    /**
-     * Deletes a state file. Deleting one that is not there is not an error.
-     */
-    deleteState(stateFileName: string): Promise<void>;
     /**
      * The id of the lock currently held, or `undefined` when the app is unlocked.
      */
@@ -34,17 +30,22 @@ export declare class TestStateProvider implements IStateProvider {
      */
     listStates(prefix: string): Promise<string[]>;
     /**
-     * Takes the app lock.
+     * Takes the app lock. With `lockId`, resumes the run already holding it.
      *
-     * @throws {@link TransactionError} When a lock is held, naming the id that holds it.
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it. When `lockId`
+     * is given and is not the lock held.
+     */
+    lockApp(lockId?: string): ReturnType<IStateProvider['lockApp']>;
+    /**
+     * Does nothing: the state lives in this process alone, so it is always the newest.
      */
-    lockApp(): Promise<{
-        lockId: string;
+    refreshState(): Promise<{
+        replaced: boolean;
     }>;
     /**
-     * Writes a state file, overwriting whatever was there.
+     * Writes state files, overwriting whatever was there and deleting each one given no `data`.
      */
-    saveState(stateFileName: string, data: Buffer): Promise<void>;
+    saveStates(stateFiles: Parameters<IStateProvider['saveStates']>[0]): Promise<void>;
     /**
      * Releases the app lock.
      *

package/dist/services/state-management/test.state-provider.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
-import { TransactionError } from '../../errors/index.js';
+import { readFile } from 'node:fs/promises';
+import { AppLockError, TransactionError } from '../../errors/index.js';
 /**
  * Keeps state in memory, and discards it when the process ends. For tests.
  *
@@ -12,12 +13,6 @@ export class TestStateProvider {
         this.localState = {};
         this.lockId = undefined;
     }
-    /**
-     * Deletes a state file. Deleting one that is not there is not an error.
-     */
-    async deleteState(stateFileName) {
-        delete this.localState[stateFileName];
-    }
     /**
      * The id of the lock currently held, or `undefined` when the app is unlocked.
      */
@@ -56,22 +51,48 @@ export class TestStateProvider {
         return Object.keys(this.localState).filter((stateFileName) => stateFileName.startsWith(prefix));
     }
     /**
-     * Takes the app lock.
+     * Takes the app lock. With `lockId`, resumes the run already holding it.
      *
-     * @throws {@link TransactionError} When a lock is held, naming the id that holds it.
+     * @throws {@link TransactionError} When a lock is held, naming the id that holds it. When `lockId`
+     * is given and is not the lock held.
      */
-    async lockApp() {
+    async lockApp(lockId) {
+        if (lockId) {
+            if (this.lockId !== lockId) {
+                throw new AppLockError(`App is not locked with lock ID "${lockId}"!`, { reason: 'not-held' });
+            }
+            return { lockId };
+        }
         if (this.lockId) {
-            throw new TransactionError(`App already locked with lock ID "${this.lockId}"!`);
+            throw new AppLockError(`App already locked with lock ID "${this.lockId}"!`, {
+                holder: { lockId: this.lockId },
+                reason: 'held',
+            });
         }
         this.lockId = randomUUID();
         return { lockId: this.lockId };
     }
     /**
-     * Writes a state file, overwriting whatever was there.
+     * Does nothing: the state lives in this process alone, so it is always the newest.
      */
-    async saveState(stateFileName, data) {
-        this.localState[stateFileName] = data;
+    async refreshState() {
+        return { replaced: false };
+    }
+    /**
+     * Writes state files, overwriting whatever was there and deleting each one given no `data`.
+     */
+    async saveStates(stateFiles) {
+        for (const stateFile of stateFiles) {
+            if ('filePath' in stateFile) {
+                this.localState[stateFile.stateFileName] = await readFile(stateFile.filePath);
+            }
+            else if (stateFile.data === undefined) {
+                delete this.localState[stateFile.stateFileName];
+            }
+            else {
+                this.localState[stateFile.stateFileName] = stateFile.data;
+            }
+        }
     }
     /**
      * Releases the app lock.

package/dist/services/state-management/test.state-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"test.state-provider.js","sourceRoot":"","sources":["../../../src/services/state-management/test.state-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IAA9B;QACmB,eAAU,GAA8B,EAAE,CAAC;QAEpD,WAAM,GAAuB,SAAS,CAAC;IAsFjD,CAAC;IApFC;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,aAAqB;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,aAAqB;QAClC,IAAI,CAAC,CAAC,aAAa,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,MAAc;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAClG,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,gBAAgB,CAAC,oCAAoC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QAE3B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,aAAqB,EAAE,IAAY;QACjD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"test.state-provider.js","sourceRoot":"","sources":["../../../src/services/state-management/test.state-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGvE;;;;;;GAMG;AACH,MAAM,OAAO,iBAAiB;IAA9B;QACmB,eAAU,GAA8B,EAAE,CAAC;QAEpD,WAAM,GAAuB,SAAS,CAAC;IAwGjD,CAAC;IAtGC;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,aAAqB;QAClC,IAAI,CAAC,CAAC,aAAa,IAAI,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACxC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,MAAc;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,MAAc;QAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,aAAa,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAClG,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,MAAe;QAC3B,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC3B,MAAM,IAAI,YAAY,CAAC,mCAAmC,MAAM,IAAI,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;YAChG,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,YAAY,CAAC,oCAAoC,IAAI,CAAC,MAAM,IAAI,EAAE;gBAC1E,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;gBAC/B,MAAM,EAAE,MAAM;aACf,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QAE3B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY;QAChB,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,UAAuD;QACtE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,UAAU,IAAI,SAAS,EAAE,CAAC;gBAC5B,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,MAAM,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;YAChF,CAAC;iBAAM,IAAI,SAAS,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACxC,OAAO,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC;YAC5D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,MAAc;QAC5B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,gBAAgB,CAAC,kBAAkB,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IAC1B,CAAC;CACF"}

package/dist/services/terraform/terraform.service.d.ts

@@ -7,6 +7,10 @@ import { HclExpression, TerraformData, type TerraformLiteralType, TerraformResou
  * - Commit (tfstate outputs -> response population).
  */
 interface OctoTerraformResourceMapping {
+    /**
+     * Whether destroying the octo resource loses data, as its class declares.
+     */
+    destroyLosesData: boolean;
     /**
      * Set for external resources only: the single output carrying the entire response map.
      */
@@ -53,8 +57,15 @@ export interface OctoTerraformResourceScope<TResponse extends BaseResourceSchema
      * Emits one `resource "<type>" "<name>"` block for this octo resource.
      * Multiple calls chain via `depends_on` in call order.
      * The provider alias is applied automatically when the resource was registered with a provider context.
+     *
+     * Pass `options.chain: false` to keep a block out of the chain: it depends on neither the block
+     * before it nor is depended on by the block after it, and waits only on what its attributes
+     * reference. Use it for a block emitted once per item, like a file upload, where a chain would run
+     * the items one at a time and store every earlier address in each item's terraform state.
      */
-    addTerraformResource(type: string, name: string, spec?: Record<string, unknown>): TerraformResource;
+    addTerraformResource(type: string, name: string, spec?: Record<string, unknown>, options?: {
+        chain?: boolean;
+    }): TerraformResource;
     /**
      * Declares the outputs for this resource — one entry per response key.
      * Every response key must be declared; the commit phase reads exactly these outputs to
@@ -119,6 +130,18 @@ export interface TerraformModuleScope {
      */
     getRef<T extends UnknownResource>(resource: T, key: keyof ResourceSchema<T>['response'] & string): HclExpression;
     getRef<S extends BaseResourceSchema>(resource: MatchingResource<S>, key: keyof S['response'] & string): HclExpression;
+    /**
+     * Joins text and references into one quoted terraform string, for when a value is another
+     * resource's output with text of this resource's own around it. Each reference resolves as
+     * {@link TerraformModuleScope.getRef} does, so a producer in another folder is still wired in.
+     *
+     * @example
+     * ```ts
+     * // "https://${var.distribution_DomainName}/api/orders"
+     * terraform.interpolate('https://', terraform.getRef(distribution, 'DomainName'), '/api/orders');
+     * ```
+     */
+    interpolate(...parts: (string | HclExpression)[]): HclExpression;
     /**
      * Wraps a value in a `jsonencode(...)` call.
      */
@@ -262,12 +285,25 @@ export declare class TerraformService {
      * expected rather than unattributed.
      */
     getResourceReferrers(): Map<string, Set<string>>;
+    /**
+     * Records that a resource takes over the terraform state of a resource octo committed, so terraform
+     * updates or replaces the infrastructure in place instead of creating the new resource beside the old.
+     * Within one folder, the folder renders a `moved` block from each of the old resource's addresses to
+     * the new one's. Between folders, the folder record lists the move, and `TerraformUtility`
+     * moves the state before terraform runs.
+     */
+    moveResource(fromModuleId: string, fromResourceId: string, toModuleId: string, toResourceId: string): void;
     /**
      * Phase 2 of rendering: prints the four files of every folder from the wiring computed in
      * phase 1. Makes no decisions — when a {@link RefHclNode} renders, its answer is looked up in the
      * folder's precomputed `resolvedRefs`. Cross-folder dependency cycles throw (in phase 1).
+     *
+     * A folder also keeps every provider block `previousFolders` recorded for it that none of its
+     * resources use any more, so terraform can still destroy what that provider created. A resource
+     * whose id moved to another account, for one, leaves its old address in the folder's state, bound
+     * to the old account's provider.
      */
-    renderAllModules(): Map<string, TerraformModuleFiles>;
+    renderAllModules(previousFolders?: TerraformFolderOutput[]): Map<string, TerraformModuleFiles>;
     /**
      * Prints the four files of an **empty** folder from a recorded folder: a `main.tf` with the
      * config block rebuilt from the recorded `required_providers` entries (plus null/external when
@@ -346,6 +382,20 @@ export declare class TerraformService {
      * registered wins, since the alias only routes the region.
      */
     private findProvider;
+    /**
+     * The moves of a folder's record: the resources whose state moves in from another folder, with the
+     * outputs their consumers in other folders read.
+     */
+    private getFolderMoves;
+    /**
+     * The addresses a resource's state moves between. A block named `<resourceId><suffix>` moves from the
+     * block the old resource named `<its resourceId><suffix>`; a `from` the state does not hold moves nothing.
+     */
+    private getMoveAddresses;
+    /**
+     * The `moved` addresses of a folder, for the resources taking over a state the same folder holds.
+     */
+    private getMovedAddresses;
     /**
      * @internal
      */
@@ -354,6 +404,10 @@ export declare class TerraformService {
      * @internal
      */
     private getRef;
+    /**
+     * @internal
+     */
+    private interpolate;
     /**
      * @internal
      */
@@ -388,7 +442,7 @@ export declare class TerraformService {
     private renderConfigBlock;
     /**
      * Prints one folder's `terragrunt.hcl`: a `dependency` block per producer folder (with
-     * `mock_outputs`, shallow-merged over any applied state, so `run-all plan` works both before the
+     * `mock_outputs`, shallow-merged over any applied state, so `run --all -- plan` works both before the
      * first apply and when intent renames a producer resource), and the `inputs` map wiring each auto
      * variable to the producer's output.
      */