@kensio/yulin 1.21.14 → 1.21.16

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-factory.d.ts

@@ -1,33 +1,43 @@
 import type { SimCfnServiceResourceFactory } from "../../cloudformation/resource/factory/sim-cfn-resource-factory.type.js";
 import type { SimCfnResource, SimCloudFormationResourceCreateContext, SimCloudFormationResourceDeleteContext } from "../../cloudformation/resource/sim-cfn-resource.js";
+import type { SimCloudFormationResourceInPlaceUpdateContext } from "../../cloudformation/resource/sim-cfn-resource.type.js";
 import type { SimSecretsManager } from "../sim-secrets-manager.js";
 interface SimSecretsManagerCfnResourceFactoryProperties {
     readonly secretsManager: SimSecretsManager;
 }
 /**
  * CloudFormation Resource factory for simulated Secrets Manager resources.
+ *
+ * Only `Secret` is deployed. Rotation, resource policies and target
+ * attachments are not simulated, so their Resource types are reported as
+ * unsupported and skipped rather than quietly treated as deployed.
  */
 export declare class SimSecretsManagerCfnResourceFactory implements SimCfnServiceResourceFactory {
-    private readonly secretsManager;
     private readonly secretCreator;
+    private readonly secretUpdater;
+    private readonly secretDeleter;
     constructor(properties: SimSecretsManagerCfnResourceFactoryProperties);
     /**
      * Create a simulated Secrets Manager resource from a CloudFormation
      * Resource.
-     *
-     * Rotation, resource policies and target attachments are not simulated, so
-     * their Resource types are reported as unsupported and skipped rather than
-     * quietly treated as deployed.
      */
     create(resourceTypeName: string, resource: SimCfnResource, context: SimCloudFormationResourceCreateContext): Promise<object | undefined>;
+    /**
+     * Whether a changed secret can be applied to the deployed one.
+     *
+     * Name is the only property real CloudFormation replaces a secret for.
+     * Everything else is applied with no interruption, which is what keeps a
+     * generated value across a change to the secret's description or tags.
+     */
+    updatesInPlace(resourceTypeName: string, current: SimCfnResource, updated: SimCfnResource): boolean;
+    /**
+     * Apply a changed AWS::SecretsManager::Secret Resource to the deployed
+     * secret.
+     */
+    updateInPlace(resourceTypeName: string, current: SimCfnResource, updated: SimCfnResource, context: SimCloudFormationResourceInPlaceUpdateContext): Promise<object | undefined>;
     /**
      * Delete a simulated Secrets Manager resource created from a CloudFormation
      * Resource.
-     *
-     * DeleteSecret schedules the deletion rather than carrying it out, so a torn
-     * down Stack leaves a secret waiting out its recovery window. That is what
-     * CloudFormation does: the secret is recoverable afterwards, which is the
-     * point of the window.
      */
     delete(resourceTypeName: string, resource: SimCfnResource, context: SimCloudFormationResourceDeleteContext): Promise<void>;
 }

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-factory.js

@@ -1,51 +1,65 @@
 import { simCfnResourceCallerOptions } from "../../cloudformation/resource/caller/sim-cfn-resource-caller-options.js";
 import { SimCfnSecretsManagerSecretCreator } from "./secret/sim-cfn-secrets-manager-secret-creator.js";
-import { assertDefined } from "../../../util/type-guard/defined.js";
+import { SimCfnSecretsManagerSecretDeleter } from "./secret/sim-cfn-secrets-manager-secret-deleter.js";
+import { SimCfnSecretsManagerSecretUpdater } from "./secret/sim-cfn-secrets-manager-secret-updater.js";
+import { simCfnSecretsManagerSecretReplaced } from "./secret/sim-cfn-secrets-manager-secret-change.js";
+import { isSimCfnSecretsManagerSecret, requireSimCfnSecretsManagerSecret, } from "./sim-cfn-secrets-manager-resource-type.js";
 /**
  * CloudFormation Resource factory for simulated Secrets Manager resources.
+ *
+ * Only `Secret` is deployed. Rotation, resource policies and target
+ * attachments are not simulated, so their Resource types are reported as
+ * unsupported and skipped rather than quietly treated as deployed.
  */
 export class SimSecretsManagerCfnResourceFactory {
-    secretsManager;
     secretCreator;
+    secretUpdater;
+    secretDeleter;
     constructor(properties) {
-        this.secretsManager = properties.secretsManager;
+        const { secretsManager } = properties;
         this.secretCreator = new SimCfnSecretsManagerSecretCreator({
-            secretsManager: properties.secretsManager,
+            secretsManager,
+        });
+        this.secretUpdater = new SimCfnSecretsManagerSecretUpdater({
+            secretsManager,
+        });
+        this.secretDeleter = new SimCfnSecretsManagerSecretDeleter({
+            secretsManager,
         });
     }
     /**
      * Create a simulated Secrets Manager resource from a CloudFormation
      * Resource.
-     *
-     * Rotation, resource policies and target attachments are not simulated, so
-     * their Resource types are reported as unsupported and skipped rather than
-     * quietly treated as deployed.
      */
     async create(resourceTypeName, resource, context) {
-        switch (resourceTypeName) {
-            case "Secret": {
-                return await this.secretCreator.create(resource, context.resolvedProperties ?? resource.properties, simCfnResourceCallerOptions(context.caller));
-            }
-            default: {
-                throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName}`);
-            }
-        }
+        requireSimCfnSecretsManagerSecret(resourceTypeName);
+        return await this.secretCreator.create(resource, context.resolvedProperties ?? resource.properties, simCfnResourceCallerOptions(context.caller));
+    }
+    /**
+     * Whether a changed secret can be applied to the deployed one.
+     *
+     * Name is the only property real CloudFormation replaces a secret for.
+     * Everything else is applied with no interruption, which is what keeps a
+     * generated value across a change to the secret's description or tags.
+     */
+    updatesInPlace(resourceTypeName, current, updated) {
+        return (isSimCfnSecretsManagerSecret(resourceTypeName) &&
+            !simCfnSecretsManagerSecretReplaced(current, updated));
+    }
+    /**
+     * Apply a changed AWS::SecretsManager::Secret Resource to the deployed
+     * secret.
+     */
+    async updateInPlace(resourceTypeName, current, updated, context) {
+        requireSimCfnSecretsManagerSecret(resourceTypeName, "update");
+        return await this.secretUpdater.update(current, updated, context);
     }
     /**
      * Delete a simulated Secrets Manager resource created from a CloudFormation
      * Resource.
-     *
-     * DeleteSecret schedules the deletion rather than carrying it out, so a torn
-     * down Stack leaves a secret waiting out its recovery window. That is what
-     * CloudFormation does: the secret is recoverable afterwards, which is the
-     * point of the window.
      */
     async delete(resourceTypeName, resource, context) {
-        if (resourceTypeName !== "Secret") {
-            throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName} deletion`);
-        }
-        const secret = resource.simResource;
-        assertDefined(secret, `sim Secrets Manager secret for CloudFormation Resource ${resource.logicalId}`);
-        await this.secretsManager.deleteSecret({ input: { SecretId: secret.arn.value } }, simCfnResourceCallerOptions(context.caller));
+        requireSimCfnSecretsManagerSecret(resourceTypeName, "deletion");
+        await this.secretDeleter.delete(resource, simCfnResourceCallerOptions(context.caller));
     }
 }

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-type.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether a Resource type name is the secret this simulation deploys.
+ */
+export declare function isSimCfnSecretsManagerSecret(resourceTypeName: string): boolean;
+/**
+ * Refuse an operation on a Resource type this simulation does not deploy.
+ *
+ * The refusal reads as an unsupported Resource, so the Stack records it and
+ * carries on rather than failing. Creation names no operation, since a
+ * Resource type nothing creates is the plain case a reader meets first.
+ */
+export declare function requireSimCfnSecretsManagerSecret(resourceTypeName: string, operation?: string): void;

package/dist/service/secretsmanager/cfn/sim-cfn-secrets-manager-resource-type.js

@@ -0,0 +1,22 @@
+/** The one AWS::SecretsManager::* Resource type this simulation deploys. */
+const secretResourceTypeName = "Secret";
+/**
+ * Whether a Resource type name is the secret this simulation deploys.
+ */
+export function isSimCfnSecretsManagerSecret(resourceTypeName) {
+    return resourceTypeName === secretResourceTypeName;
+}
+/**
+ * Refuse an operation on a Resource type this simulation does not deploy.
+ *
+ * The refusal reads as an unsupported Resource, so the Stack records it and
+ * carries on rather than failing. Creation names no operation, since a
+ * Resource type nothing creates is the plain case a reader meets first.
+ */
+export function requireSimCfnSecretsManagerSecret(resourceTypeName, operation) {
+    if (isSimCfnSecretsManagerSecret(resourceTypeName)) {
+        return;
+    }
+    const refused = operation === undefined ? "" : ` ${operation}`;
+    throw new Error(`Unsupported sim Secrets Manager CloudFormation Resource ${resourceTypeName}${refused}`);
+}

package/dist/util/background/background-clock-waits.d.ts

@@ -26,10 +26,17 @@ export declare class BackgroundClockWaits {
      */
     around<T>(wait: BackgroundClockWait, work: () => Promise<T>): Promise<T>;
     /**
-     * The work in a set that is neither waiting on the clock nor the work asking
-     * about it.
+     * The work in a set that completion has anything to wait for.
+     *
+     * The work asking is always left out. Waiting for the invocation the asking
+     * code is part of would be waiting for itself.
+     *
+     * Work waiting on the clock is left out where simulated time stands still,
+     * since only a caller moving the clock brings the instant it waits for, and
+     * that caller is the one waiting here. A running clock reaches the instant on
+     * its own, and this waits for the work to get there.
      */
-    runnable(held: ReadonlyMap<Promise<unknown>, BackgroundClockWait>): Promise<unknown>[];
+    runnable(held: ReadonlyMap<Promise<unknown>, BackgroundClockWait>, clockIsRunning?: boolean): Promise<unknown>[];
     /**
      * Whether the code running now is already inside outstanding work, and so
      * already counted.

package/dist/util/background/background-clock-waits.js

@@ -23,14 +23,21 @@ export class BackgroundClockWaits {
         return await this.storage.run(wait, work);
     }
     /**
-     * The work in a set that is neither waiting on the clock nor the work asking
-     * about it.
+     * The work in a set that completion has anything to wait for.
+     *
+     * The work asking is always left out. Waiting for the invocation the asking
+     * code is part of would be waiting for itself.
+     *
+     * Work waiting on the clock is left out where simulated time stands still,
+     * since only a caller moving the clock brings the instant it waits for, and
+     * that caller is the one waiting here. A running clock reaches the instant on
+     * its own, and this waits for the work to get there.
      */
-    runnable(held) {
+    runnable(held, clockIsRunning = false) {
         const own = this.storage.getStore();
         return held
             .entries()
-            .filter(([, wait]) => wait.count === 0 && wait !== own)
+            .filter(([, wait]) => wait !== own && (clockIsRunning || wait.count === 0))
             .map(([promise]) => promise)
             .toArray();
     }

package/dist/util/background/background-pending-tasks.d.ts

@@ -35,21 +35,27 @@ export declare class BackgroundPendingTasks {
      */
     get size(): number;
     /**
-     * Wait until nothing is outstanding but work that is waiting on the clock.
+     * Wait until nothing is outstanding that can still get somewhere.
      *
-     * Work that parks part way through ends the wait rather than extending it:
-     * only moving the clock releases it, and moving the clock is what waits
-     * here. The loop then looks again at what is left running, so work that
-     * carries on is waited for again.
+     * Where simulated time stands still, work that parks on the clock ends the
+     * wait rather than extending it. Only moving the clock releases it, and
+     * moving the clock is what waits here. The loop then looks again at what is
+     * left running, so work that carries on is waited for again.
+     *
+     * A running clock reaches those instants by itself, and the work parked on
+     * them is waited for like any other. What bounds the wait is the instant
+     * itself, which arrives in the real time between here and there.
      */
-    complete(): Promise<void>;
+    complete(clockIsRunning?: boolean): Promise<void>;
     /**
-     * The work completion has anything to wait for, which is whatever is
-     * neither waiting on the clock nor waiting for completion itself.
+     * The work completion has anything to wait for.
      *
      * Work that asks for the simulation to settle from inside itself is left
      * out. A handler advancing the clock is the ordinary case, and waiting for
      * the invocation it is part of would be waiting for itself.
+     *
+     * Work waiting on the clock joins it once simulated time is running, since
+     * a running clock is what brings the instant it waits for.
      */
-    running(): Promise<unknown>[];
+    running(clockIsRunning?: boolean): Promise<unknown>[];
 }

package/dist/util/background/background-pending-tasks.js

@@ -52,15 +52,19 @@ export class BackgroundPendingTasks {
         return this.#held.size;
     }
     /**
-     * Wait until nothing is outstanding but work that is waiting on the clock.
+     * Wait until nothing is outstanding that can still get somewhere.
      *
-     * Work that parks part way through ends the wait rather than extending it:
-     * only moving the clock releases it, and moving the clock is what waits
-     * here. The loop then looks again at what is left running, so work that
-     * carries on is waited for again.
+     * Where simulated time stands still, work that parks on the clock ends the
+     * wait rather than extending it. Only moving the clock releases it, and
+     * moving the clock is what waits here. The loop then looks again at what is
+     * left running, so work that carries on is waited for again.
+     *
+     * A running clock reaches those instants by itself, and the work parked on
+     * them is waited for like any other. What bounds the wait is the instant
+     * itself, which arrives in the real time between here and there.
      */
-    async complete() {
-        let running = this.running();
+    async complete(clockIsRunning = false) {
+        let running = this.running(clockIsRunning);
         while (running.length > 0) {
             // oxlint-disable-next-line no-await-in-loop
             const settled = await Promise.race([
@@ -68,19 +72,21 @@ export class BackgroundPendingTasks {
                 this.#clockWaits.next,
             ]);
             new BackgroundSettledTasks(settled).throwFirstFailure();
-            running = this.running();
+            running = this.running(clockIsRunning);
         }
     }
     /**
-     * The work completion has anything to wait for, which is whatever is
-     * neither waiting on the clock nor waiting for completion itself.
+     * The work completion has anything to wait for.
      *
      * Work that asks for the simulation to settle from inside itself is left
      * out. A handler advancing the clock is the ordinary case, and waiting for
      * the invocation it is part of would be waiting for itself.
+     *
+     * Work waiting on the clock joins it once simulated time is running, since
+     * a running clock is what brings the instant it waits for.
      */
-    running() {
-        return this.#clockWaits.runnable(this.#held);
+    running(clockIsRunning = false) {
+        return this.#clockWaits.runnable(this.#held, clockIsRunning);
     }
     /**
      * Keep work outstanding under its own record until it settles.

package/dist/util/background/background.d.ts

@@ -141,9 +141,11 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
      *
-     * Work waiting on the clock is not waited for: it is not outstanding, it is
-     * scheduled for a simulated instant that has not arrived. Only moving the
-     * clock releases it.
+     * What happens to work waiting on the clock follows the clock. Where
+     * simulated time stands still the work stays where it is, scheduled for an
+     * instant only a caller can bring, and this returns without it. Where
+     * simulated time runs, the instant arrives by itself and this waits for the
+     * work to get through it.
      */
     complete(): Promise<void>;
     /**
@@ -154,5 +156,11 @@ export declare class BackgroundTasks implements BackgroundScheduler, BackgroundC
      * See how many tasks are waiting for simulated time to reach them.
      */
     get dueTaskCount(): number;
+    /**
+     * Whether simulated time reaches a scheduled instant on its own.
+     *
+     * A clock with nothing to say about it advances, as the host clock does.
+     */
+    private get clockIsRunning();
 }
 export {};

package/dist/util/background/background.js

@@ -79,12 +79,14 @@ export class BackgroundTasks {
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
      *
-     * Work waiting on the clock is not waited for: it is not outstanding, it is
-     * scheduled for a simulated instant that has not arrived. Only moving the
-     * clock releases it.
+     * What happens to work waiting on the clock follows the clock. Where
+     * simulated time stands still the work stays where it is, scheduled for an
+     * instant only a caller can bring, and this returns without it. Where
+     * simulated time runs, the instant arrives by itself and this waits for the
+     * work to get through it.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clockIsRunning);
     }
     /**
      * See how many outstanding background tasks are scheduled.
@@ -98,4 +100,12 @@ export class BackgroundTasks {
     get dueTaskCount() {
         return this.dueTasks.size;
     }
+    /**
+     * Whether simulated time reaches a scheduled instant on its own.
+     *
+     * A clock with nothing to say about it advances, as the host clock does.
+     */
+    get clockIsRunning() {
+        return this.clock.advances !== false;
+    }
 }

package/dist/util/background/non-deterministic-background.d.ts

@@ -55,6 +55,10 @@ export declare class NonDeterministicBackgroundTasks implements BackgroundSchedu
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     complete(): Promise<void>;
     /**

package/dist/util/background/non-deterministic-background.js

@@ -79,9 +79,13 @@ export class NonDeterministicBackgroundTasks {
     /**
      * Wait until all tasks currently scheduled have finished.
      * If tasks schedule more tasks, this will continue draining until idle.
+     *
+     * Work waiting on the clock is waited for where simulated time runs, and
+     * left where it is where simulated time stands still, exactly as it is on
+     * the deterministic scheduler.
      */
     async complete() {
-        await this.pending.complete();
+        await this.pending.complete(this.clock.advances !== false);
     }
     /**
      * See how many outstanding background tasks are scheduled.

package/dist/util/clock/sim-clock.d.ts

@@ -11,6 +11,18 @@ export interface SimClock {
      * Get the current time in this simulation.
      */
     now(): Date;
+    /**
+     * Whether simulated time moves on this clock by itself.
+     *
+     * A scheduler reads this to decide what waiting for a simulation to settle
+     * means. Time that advances brings the instant a task is scheduled for on
+     * its own, and settling waits for that task. Time that stands still leaves
+     * the instant to whoever moves the clock, and settling leaves the task where
+     * it is.
+     *
+     * A clock that says nothing advances, as the host clock does.
+     */
+    readonly advances?: boolean;
 }
 /**
  * Clock that reports the real system time.
@@ -19,6 +31,8 @@ export interface SimClock {
  * something deliberately replaces it.
  */
 export declare class SimRealClock implements SimClock {
+    /** Real time moves by itself. */
+    readonly advances = true;
     /**
      * Get the current real system time.
      */
@@ -31,6 +45,8 @@ export declare class SimRealClock implements SimClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export declare class SimFixedClock implements SimClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    readonly advances = false;
     private readonly instant;
     constructor(instant: Date);
     /**

package/dist/util/clock/sim-clock.js

@@ -5,6 +5,8 @@
  * something deliberately replaces it.
  */
 export class SimRealClock {
+    /** Real time moves by itself. */
+    advances = true;
     /**
      * Get the current real system time.
      */
@@ -19,6 +21,8 @@ export class SimRealClock {
  * reaching for a library that replaces the clock for the whole process.
  */
 export class SimFixedClock {
+    /** A fixed instant is the whole of this clock. Time stands still on it. */
+    advances = false;
     instant;
     constructor(instant) {
         this.instant = new Date(instant);

package/dist/util/clock/sim-controllable-clock.d.ts

@@ -33,6 +33,17 @@ export declare class SimControllableClock implements SimClock {
      * Whether simulated time is currently standing still.
      */
     get isFrozen(): boolean;
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances(): boolean;
     /**
      * Stop simulated time where it currently reads.
      */

package/dist/util/clock/sim-controllable-clock.js

@@ -32,6 +32,19 @@ export class SimControllableClock {
     get isFrozen() {
         return this.mode.isFrozen;
     }
+    /**
+     * Whether simulated time moves here by itself.
+     *
+     * A frozen clock moves only where something moves it. So does a running
+     * clock over a base that stands still. The offset a running mode applies is
+     * fixed, so simulated time here moves exactly as far as the clock underneath
+     * moves, and a fixed clock underneath moves nowhere. Freezing and resuming
+     * such a clock changes which instant it reports and leaves it as still as it
+     * was.
+     */
+    get advances() {
+        return !this.mode.isFrozen && this.base.advances !== false;
+    }
     /**
      * Stop simulated time where it currently reads.
      */

package/docs/services/cloudformation/README.md

@@ -446,6 +446,22 @@ Replacement also affects dependencies and retention policies:
   The deployed one was deleted to make room for the replacement, and there is nothing left to put
   back. See [rolling back a failed update](#rolling-back-a-failed-update) below.
 
+### Resources a service changes where they are
+
+A service can claim a change for the properties real CloudFormation applies with no interruption.
+The resource is then left where it is. It keeps its physical name and everything it holds, and
+every resource naming it is left standing too.
+
+`AWS::SecretsManager::Secret` is the one resource type that does this so far. `Name` is the only
+property real CloudFormation replaces a secret for. A change to anything else is applied to the
+deployed secret, which keeps its ARN and its versions across the update. See the
+[simulated Secrets Manager docs](https://yulinsim.dev/services/secretsmanager/ "Simulated Secrets Manager usage docs")
+for which changes write a new secret version and which leave the value alone.
+
+These changes are applied first, while everything the stack had is still deployed. An update that
+fails on one has deleted nothing yet. A claimed resource the replacement spread reaches is replaced
+after all, and the claim is taken back, since its dependency is being deleted and created again.
+
 ### Rolling back a failed update
 
 A failed update is rolled back onto the template the stack was deployed from. The stack moves to
@@ -4393,13 +4409,15 @@ Each service's own docs describe what its resource types support.
   [properties a Resource was created without](#properties-a-resource-was-created-without) for what
   is still refused outright.
 - A stack update replaces a changed resource rather than updating it in place, so what the resource
-  held is lost. See [changed resources are replaced](#changed-resources-are-replaced).
+  held is lost. `AWS::SecretsManager::Secret` is the exception. See
+  [changed resources are replaced](#changed-resources-are-replaced) and
+  [resources a service changes where they are](#resources-a-service-changes-where-they-are).
 - A watched template file updates its stack in place. That makes the update itself no gentler. A
   changed resource is still replaced and loses what it holds, the same as any other update.
 - Yulin never synthesizes a CDK app. It watches the synthesized output template. A change to the app
   itself reaches the stack once something has run `cdk synth` over it.
-- A change set reports every `Modify` as `Replacement: True`, because a changed resource is replaced
-  rather than updated in place. `ChangeSetType: IMPORT` is refused, and so is a `CREATE` change set
+- A change set reports every `Modify` as `Replacement: True`, even for a resource an update would
+  change where it is. `ChangeSetType: IMPORT` is refused, and so is a `CREATE` change set
   naming a stack that is already there, where CloudFormation allows a second one against a stack
   still in review. Drift detection is outside the simulation.
 - A rolled-back update recreates a resource it had already replaced, and the resource comes back

package/docs/services/lambda/README.md

@@ -3269,6 +3269,17 @@ An interval runs once for each period an advance covers. Advancing eleven second
 interval runs it five times. A delay of zero, or none at all, is due at the instant it was asked
 for, and a handler yielding with `setTimeout(resolve, 0)` gets going again without the clock moving.
 
+Where the clock is left running, the delay passes in real time and nothing has to move it.
+`simAws.backgroundTasksComplete()` waits for a handler sleeping on a clock that is moving. An S3
+event notification, a stream record or an asynchronous invocation whose handler uses a timer has
+finished by the time the drain returns, and the function's `Timeout` bounds how long that wait can
+last.
+
+Two things leave a clock standing still. `freeze()`, `advanceBy(...)` and `setTo(...)` all leave it
+frozen, and a `SimAws` built on a `SimFixedClock` reports one instant however long the host runs.
+Under either the drain comes back while the handler sleeps, and moving the clock is what releases
+it.
+
 The function's `Timeout` is a deadline on the same clock. Where it arrives before the handler
 answers, the invocation ends in the error the real runtime reports.
 

package/docs/services/secretsmanager/README.md

@@ -428,6 +428,37 @@ console.log(credentials.password?.length); // 24
 Generated passwords are random. Read the deployed value through Secrets Manager instead of asserting
 on an exact password.
 
+## Updating a deployed secret
+
+`Name` is the only property real CloudFormation replaces a secret for. A stack update that changes
+anything else applies it to the deployed secret, which keeps its ARN and its versions.
+
+A change to the description, the tags or the KMS key leaves the value alone. That is what carries a
+generated password across an update, and it keeps a resource that read the secret as the stack
+deployed, such as a CloudFront origin custom header, holding the value the secret still has.
+
+A new version is written when the template asks for a different value, which is a changed
+`SecretString` or a changed `GenerateSecretString`. A changed `GenerateSecretString` generates a new
+password, as real CloudFormation writes a new version for one. **A resource that resolved the old
+value keeps it.** Its own template entry is unchanged, so the update leaves it alone, and it goes on
+holding what it read at deploy time. A consumer that has to follow the value must read the secret
+when it runs, the way a Lambda function given the secret's ARN does, rather than take a copy through
+a `{{resolve:secretsmanager:...}}` reference.
+
+The template is the desired state. A property the new template leaves out is cleared. A dropped
+`Description` is emptied, and a dropped `KmsKeyId` puts the secret back on the `aws/secretsmanager`
+key. Versions already written keep the key they were made with and stay
+readable.
+
+Changing the `Name` replaces the secret. The new one is created under the new name and the old one
+is scheduled for deletion, waiting out its recovery window.
+
+A secret is also replaced when a resource it names is replaced, because the update deletes and
+recreates that resource and the secret would otherwise be applied against the one on its way out.
+That replacement then fails, since the name is held for the recovery window. Real CloudFormation
+updates the secret in place and hands it the new physical name. Nothing is applied to the deployed
+secret before the failure.
+
 ## Reading a secret with a dynamic reference
 
 A `{{resolve:secretsmanager:...}}` dynamic reference reads an existing secret while CloudFormation
@@ -641,7 +672,10 @@ code into the simulation, served in process. See
   empty page.
 - Tags are stored and reported by `DescribeSecret` and `ListSecrets`, but `TagResource` and
   `UntagResource` are absent, and the `secretsmanager:ResourceTag` and `aws:ResourceTag` condition
-  keys are left underived.
+  keys are left underived. A stack update applies the tags its template declares to the deployed
+  secret, since there is no command to ask for it with.
+- A stack update authorizes the whole change as `secretsmanager:UpdateSecret`. Real CloudFormation
+  needs `secretsmanager:TagResource` as well for a change to the tags.
 - Other Secrets Manager condition keys, such as `secretsmanager:SecretId` and
   `secretsmanager:VersionStage`, are left underived too, and a policy relying on them fails to match.
   Ordinary condition operators on values sim IAM does supply work as usual.

package/docs/time/README.md

@@ -63,6 +63,13 @@ example, a simulation advanced by one hour continues to run one hour ahead of th
 
 Read `simAws.clock().isFrozen` to check the current mode.
 
+The mode also decides what waiting for the simulation to settle means.
+`simAws.backgroundTasksComplete()` waits for background work sleeping on a clock that is moving,
+because the instant that work sleeps until arrives by itself. Under a clock standing still the same
+work is left where it is, and `advanceBy(...)` or a forward `setTo(...)` is what brings the instant
+and waits for what follows from it. A simulation built on a `SimFixedClock` stands still under a
+running mode too, since simulated time here moves only as far as the clock underneath moves.
+
 ## Advancing time
 
 `advanceBy(...)` accepts days, hours, minutes, seconds, and milliseconds. The values are added