@kensio/yulin 1.21.25 → 1.21.27

package/dist/service/scheduler/schedule/sim-scheduler-time-window.d.ts

@@ -0,0 +1,33 @@
+import type { SimRandom } from "../../../util/random/sim-random.js";
+import type { SimSchedulerFlexibleTimeWindow } from "../command/schedule/schedule.command.js";
+/**
+ * When, relative to its due time, a schedule invokes its target.
+ *
+ * With `OFF` that is the due time itself. With `FLEXIBLE` it is some moment
+ * after the due time and inside the window, which AWS chooses and does not
+ * reveal. Firing on the dot instead would let a test pass by relying on
+ * timing AWS does not promise, so each occurrence draws its own moment.
+ */
+export declare class SimSchedulerTimeWindow {
+    /**
+     * The window length in minutes, or nothing when the mode is `OFF`.
+     */
+    readonly minutes: number | undefined;
+    private constructor();
+    /**
+     * Read the window a request carries, which AWS requires on every one.
+     */
+    static of(window: SimSchedulerFlexibleTimeWindow | undefined): SimSchedulerTimeWindow;
+    /**
+     * The window as GetSchedule reports it, which is what the request sent.
+     */
+    get declared(): SimSchedulerFlexibleTimeWindow;
+    /**
+     * The instant one occurrence invokes its target, drawn from `random`.
+     *
+     * It is never before the due time and always before the window closes, so
+     * a test that moves the clock past the end of the window sees the
+     * invocation whatever was drawn.
+     */
+    invocationAt(due: Date, random: SimRandom): Date;
+}

package/dist/service/scheduler/schedule/sim-scheduler-time-window.js

@@ -0,0 +1,93 @@
+import { SimSchedulerValidationException } from "../error/sim-scheduler.error.js";
+const minimumWindowInMinutes = 1;
+const maximumWindowInMinutes = 1440;
+const millisecondsPerMinute = 60_000;
+/**
+ * Refuse a value the API model's own constraints reject, in the words AWS
+ * uses for them.
+ */
+function constraintFailure(value, member, constraint) {
+    return new SimSchedulerValidationException(`1 validation error detected: Value '${value}' at ` +
+        `'flexibleTimeWindow.${member}' failed to satisfy constraint: ` +
+        `Member must ${constraint}`);
+}
+/**
+ * Read the length of a flexible window, refusing one outside 1 to 1440.
+ */
+function windowLength(minutes) {
+    if (minutes === undefined) {
+        throw new SimSchedulerValidationException("Invalid parameter: FlexibleTimeWindow Reason: a FLEXIBLE window " +
+            "needs MaximumWindowInMinutes, from 1 to 1440");
+    }
+    if (!Number.isSafeInteger(minutes)) {
+        throw new SimSchedulerValidationException(`Invalid parameter: FlexibleTimeWindow Reason: MaximumWindowInMinutes ` +
+            `is a whole number of minutes, and ${String(minutes)} is not`);
+    }
+    if (minutes < minimumWindowInMinutes) {
+        throw constraintFailure(String(minutes), "maximumWindowInMinutes", `have value greater than or equal to ${String(minimumWindowInMinutes)}`);
+    }
+    if (minutes > maximumWindowInMinutes) {
+        throw constraintFailure(String(minutes), "maximumWindowInMinutes", `have value less than or equal to ${String(maximumWindowInMinutes)}`);
+    }
+    return minutes;
+}
+/**
+ * When, relative to its due time, a schedule invokes its target.
+ *
+ * With `OFF` that is the due time itself. With `FLEXIBLE` it is some moment
+ * after the due time and inside the window, which AWS chooses and does not
+ * reveal. Firing on the dot instead would let a test pass by relying on
+ * timing AWS does not promise, so each occurrence draws its own moment.
+ */
+export class SimSchedulerTimeWindow {
+    /**
+     * The window length in minutes, or nothing when the mode is `OFF`.
+     */
+    minutes;
+    constructor(minutes) {
+        this.minutes = minutes;
+    }
+    /**
+     * Read the window a request carries, which AWS requires on every one.
+     */
+    static of(window) {
+        const mode = window?.Mode;
+        if (mode === undefined) {
+            throw new SimSchedulerValidationException("FlexibleTimeWindow is required, and its Mode is OFF or FLEXIBLE");
+        }
+        if (mode === "FLEXIBLE") {
+            return new SimSchedulerTimeWindow(windowLength(window?.MaximumWindowInMinutes));
+        }
+        if (mode !== "OFF") {
+            throw constraintFailure(mode, "mode", "satisfy enum value set: [OFF, FLEXIBLE]");
+        }
+        if (window?.MaximumWindowInMinutes !== undefined) {
+            throw new SimSchedulerValidationException("Invalid parameter: FlexibleTimeWindow Reason: " +
+                "MaximumWindowInMinutes is only allowed when Mode is FLEXIBLE");
+        }
+        return new SimSchedulerTimeWindow(undefined);
+    }
+    /**
+     * The window as GetSchedule reports it, which is what the request sent.
+     */
+    get declared() {
+        if (this.minutes === undefined) {
+            return { Mode: "OFF" };
+        }
+        return { Mode: "FLEXIBLE", MaximumWindowInMinutes: this.minutes };
+    }
+    /**
+     * The instant one occurrence invokes its target, drawn from `random`.
+     *
+     * It is never before the due time and always before the window closes, so
+     * a test that moves the clock past the end of the window sees the
+     * invocation whatever was drawn.
+     */
+    invocationAt(due, random) {
+        if (this.minutes === undefined) {
+            return due;
+        }
+        const offset = Math.floor(random.next() * this.minutes * millisecondsPerMinute);
+        return new Date(due.getTime() + offset);
+    }
+}

package/dist/service/scheduler/sim-scheduler.d.ts

@@ -1,4 +1,5 @@
 import { type BackgroundScheduler } from "../../util/background/background.js";
+import { type SimRandom } from "../../util/random/sim-random.js";
 import type { SimSdkCommandRouter } from "../../sdk/router/sim-sdk-command-router.type.js";
 import type { SimAwsAccountRegionScope } from "../aws/sim-aws-account-region-scope.js";
 import type { SimIamInterServiceAuthZ } from "../iam/authorize/sim-iam-inter-service-auth-z.js";
@@ -21,6 +22,11 @@ interface SimSchedulerProperties {
      * in another simulated service is only reachable through SimAws.
      */
     readonly deliveryTargets?: SimSchedulerDeliveryTargets;
+    /**
+     * Where a flexible time window draws the moment each occurrence is invoked,
+     * which is the host's `Math.random` unless a test supplies its own.
+     */
+    readonly random?: SimRandom;
 }
 /**
  * Simulated EventBridge Scheduler. Handles SDK commands. Emulates AWS

package/dist/service/scheduler/sim-scheduler.js

@@ -1,4 +1,5 @@
 import { BackgroundTasks, } from "../../util/background/background.js";
+import { SimHostRandom } from "../../util/random/sim-random.js";
 import { simAwsAccountRegionScopeFactory } from "../aws/sim-aws-account-region-scope.factory.js";
 import { simIamInRegion } from "../iam/authorize/sim-iam-region-auth-z.js";
 import { SimSchedulerCommands } from "./command/sim-scheduler-commands.js";
@@ -30,7 +31,7 @@ export class SimScheduler extends SimSchedulerInspection {
     });
     constructor(properties = {}) {
         super();
-        const { accountRegionScope = simAwsAccountRegionScopeFactory.make(), background = new BackgroundTasks(), } = properties;
+        const { accountRegionScope = simAwsAccountRegionScopeFactory.make(), background = new BackgroundTasks(), random = new SimHostRandom(), } = properties;
         const iam = simIamInRegion(properties.iam, accountRegionScope.regionName);
         this.background = background;
         this.groupStore = new SimSchedulerScheduleGroupStore({
@@ -44,6 +45,7 @@ export class SimScheduler extends SimSchedulerInspection {
             background,
             deliveryTargets: properties.deliveryTargets,
             accountRegionScope,
+            random,
         });
     }
     /**

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

@@ -0,0 +1,35 @@
+/**
+ * Where a simulation draws the values AWS leaves to chance.
+ *
+ * Some AWS behaviour is unpredictable by design, such as the moment inside a
+ * Scheduler flexible time window at which the target is invoked. A simulation
+ * draws those values from here, so a test can make them repeatable by passing
+ * a seeded source and leave them unpredictable otherwise.
+ */
+export interface SimRandom {
+    /**
+     * The next value, at least 0 and less than 1.
+     */
+    next(): number;
+}
+/**
+ * Draws from the host's `Math.random`, so values differ from run to run.
+ *
+ * This is the default, because a test that passes only for one particular
+ * draw is relying on something AWS does not promise.
+ */
+export declare class SimHostRandom implements SimRandom {
+    next(): number;
+}
+/**
+ * Draws a repeatable sequence from a seed.
+ *
+ * Two sources built from the same seed give the same values in the same order,
+ * so a failure seen once can be reproduced. The generator is mulberry32, which
+ * is small and fast and has nothing to do with security.
+ */
+export declare class SimSeededRandom implements SimRandom {
+    private state;
+    constructor(seed: number);
+    next(): number;
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Draws from the host's `Math.random`, so values differ from run to run.
+ *
+ * This is the default, because a test that passes only for one particular
+ * draw is relying on something AWS does not promise.
+ */
+export class SimHostRandom {
+    next() {
+        return Math.random();
+    }
+}
+/**
+ * Draws a repeatable sequence from a seed.
+ *
+ * Two sources built from the same seed give the same values in the same order,
+ * so a failure seen once can be reproduced. The generator is mulberry32, which
+ * is small and fast and has nothing to do with security.
+ */
+export class SimSeededRandom {
+    state;
+    constructor(seed) {
+        // Only the low 32 bits of the seed take part, as the generator works on
+        // 32-bit integers.
+        this.state = Math.trunc(seed) >>> 0;
+    }
+    next() {
+        this.state = (this.state + 0x6d_2b_79_f5) >>> 0;
+        let mixed = this.state;
+        mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+        mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+        return ((mixed ^ (mixed >>> 14)) >>> 0) / 4_294_967_296;
+    }
+}

package/docs/sdk/README.md

@@ -172,6 +172,24 @@ specific commands:
 The list accepts command classes or command names. Sending another command throws
 `SimSdkCommandNotInterceptedError`.
 
+## Abort a send
+
+An intercepted client honours the `abortSignal` option of `send`, as the SDK's own HTTP handler does:
+
+`await client.send(command, { abortSignal: AbortSignal.timeout(5000) })`
+
+A signal that has already fired rejects the send before it reaches the simulation. A signal that fires
+while the simulated operation is pending rejects the send then. A Lambda handler sleeping on the
+simulation's clock is one operation that stays pending.
+
+Either way the send rejects with an `AbortError` shaped like the one the SDK throws. Its message is
+`Request aborted` and its `cause` is the signal's reason (a `TimeoutError` for
+`AbortSignal.timeout`). Match it by `error.name`.
+
+A send carrying a signal waits one turn of the host's timers before it reaches the simulation. That
+turn stands in for the request's time on the network. A timeout of 0 or 1 milliseconds set before the
+send aborts it, as it would a request to AWS.
+
 ## Intercept the DynamoDB document client
 
 The DynamoDB document client accepts plain JavaScript values. Intercept the document client object,
@@ -282,6 +300,11 @@ service throws `SimSdkUnknownServiceError`.
 - Simulated errors have SDK-shaped `name` and `$metadata` fields. They are separate classes from the
   SDK exceptions, so match them by `error.name` instead of `instanceof`.
 - The callback form of `send(command, callback)` is not supported. Use the promise form.
+- An aborted send stops waiting for its answer. The simulated operation it started still runs to the
+  end, as a request AWS has already received does.
+- Most simulated operations answer within one turn of the host's timers. A timeout longer than a few
+  milliseconds only fires during an operation that waits, such as a sleeping Lambda handler. A
+  simulated Bedrock answer cannot be delayed.
 - Yulin reads the `marshallOptions` in
   `DynamoDBDocumentClient.from(client, { marshallOptions, unmarshallOptions })` and ignores the
   `unmarshallOptions`. A stored value comes back the way a document client built with no options of

package/docs/services/eventbridge/README.md

@@ -921,6 +921,91 @@ and a rule routes the same events whether it carries them or not. They are recor
 property and the deploy stands. Nothing reads them back. A rule or a bus deployed with tags behaves
 as though the template had never named them.
 
+## Receiving events from a SaaS partner
+
+A SaaS partner such as Stripe sends events to an account through a partner event source, named like
+`aws.partner/stripe.com/ed_...`. The partner creates the source from its own account, so a test
+shares one with `addPartnerEventSource(...)`. The account then creates a partner event bus with the
+same `Name` and `EventSourceName`, and `putPartnerEvents(...)` sends events onto it as the partner
+would.
+
+```typescript sim-event-bridge-partner-events
+/**
+ * Receiving Stripe's events on a partner event bus.
+ */
+
+import {
+  CreateEventBusCommand,
+  PutPartnerEventsCommand,
+  PutRuleCommand,
+} from "@aws-sdk/client-eventbridge";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const events = simAws.eventBridge();
+const source = "aws.partner/stripe.com/ed_test_billing";
+
+// What Stripe does when an event destination is set up for the account.
+events.addPartnerEventSource(source);
+
+// What the account does to receive from it.
+await events.createEventBus(
+  new CreateEventBusCommand({ Name: source, EventSourceName: source }),
+);
+await events.putRule(
+  new PutRuleCommand({
+    Name: "subscriptions",
+    EventBusName: source,
+    EventPattern: JSON.stringify({
+      source: [{ prefix: "aws.partner/stripe.com" }],
+      "detail-type": ["customer.subscription.created"],
+    }),
+  }),
+);
+
+// What Stripe sends when a subscription starts.
+await events.putPartnerEvents(
+  new PutPartnerEventsCommand({
+    Entries: [
+      {
+        Source: source,
+        DetailType: "customer.subscription.created",
+        Detail: JSON.stringify({
+          id: "evt_test_subscription",
+          type: "customer.subscription.created",
+          data: { object: { id: "sub_test" } },
+        }),
+      },
+    ],
+  }),
+);
+
+console.log(events.receiptsOn(source)[0]?.matchedRuleNames); // ["subscriptions"]
+```
+
+`putPartnerEvents(...)` takes the entries of the partner's `PutPartnerEvents` request. Each entry's
+`Source` names a shared source, and the event goes to the bus of the same name. Rules match it on
+`source`, `detail-type` and `detail` like any other event. A target receives the usual envelope, with
+`account` set to the receiving account. Stripe puts its event type in `DetailType` and the whole
+Stripe event object, as JSON, in `Detail`. An entry whose `Source` names no shared source fails the
+whole request with `ResourceNotFoundException`.
+
+An `AWS::Events::EventBus` with `Name` and `EventSourceName` both set to the source name creates the
+same bus from a template, and a rule names it with a `Ref` to the bus.
+
+The source has to be shared before the bus is created. `CreateEventBus` fails with
+`ResourceNotFoundException` when it is missing, and a template creating the bus fails its stack, as
+both do on AWS. A `Name` that differs from the `EventSourceName` is a `ValidationException`, as is a
+`/` in the name of a bus created without one.
+
+`DescribeEventSource` reports the source as `PENDING` until its bus exists, and `ACTIVE` after.
+Deleting the bus puts it back to `PENDING`. An event sent while the source is pending is dropped,
+as AWS documents.
+
+Only the partner sends events to a partner event bus. `PutEvents` naming one is refused with a
+`ValidationException` (its `EventBusName` takes no `/`).
+
 ## Reading back a failed delivery
 
 Real EventBridge tells the caller nothing about a failed delivery. A `PutEvents` that matched a rule
@@ -981,6 +1066,125 @@ no is a modelled outcome a test may be asking for on purpose.
 `JSON.stringify` on a failure carries the message alongside the rule, the target and the event it
 names.
 
+## Retrying and dead-lettering a delivery
+
+A target can carry a `RetryPolicy` and a `DeadLetterConfig`, from `PutTargets` or from a target in an
+`AWS::Events::Rule`. The dead-letter queue receives an event once EventBridge gives up delivering it.
+
+```typescript sim-event-bridge-dead-letter
+/**
+ * Sending an event a target refused to its dead-letter queue.
+ */
+
+import {
+  PutEventsCommand,
+  PutRuleCommand,
+  PutTargetsCommand,
+} from "@aws-sdk/client-eventbridge";
+import {
+  CreateQueueCommand,
+  ReceiveMessageCommand,
+  SetQueueAttributesCommand,
+} from "@aws-sdk/client-sqs";
+
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const dlqArn = "arn:aws:sqs:us-east-1:888888888888:undelivered-orders";
+
+// A dead-letter queue admitting EventBridge for the rule.
+const { QueueUrl } = await simAws
+  .sqs()
+  .createQueue(new CreateQueueCommand({ QueueName: "undelivered-orders" }));
+await simAws.sqs().setQueueAttributes(
+  new SetQueueAttributesCommand({
+    QueueUrl,
+    Attributes: {
+      Policy: JSON.stringify({
+        Version: "2012-10-17",
+        Statement: [
+          {
+            Effect: "Allow",
+            Principal: { Service: "events.amazonaws.com" },
+            Action: "sqs:SendMessage",
+            Resource: dlqArn,
+            Condition: {
+              ArnEquals: {
+                "aws:SourceArn":
+                  "arn:aws:events:us-east-1:888888888888:rule/orders",
+              },
+            },
+          },
+        ],
+      }),
+    },
+  }),
+);
+
+// A target queue that was never created, so every delivery fails.
+await simAws.eventBridge().putRule(
+  new PutRuleCommand({
+    Name: "orders",
+    EventPattern: JSON.stringify({ source: ["orders.service"] }),
+  }),
+);
+await simAws.eventBridge().putTargets(
+  new PutTargetsCommand({
+    Rule: "orders",
+    Targets: [
+      {
+        Id: "fulfilment",
+        Arn: "arn:aws:sqs:us-east-1:888888888888:fulfilment",
+        RetryPolicy: { MaximumRetryAttempts: 2 },
+        DeadLetterConfig: { Arn: dlqArn },
+      },
+    ],
+  }),
+);
+
+await simAws.eventBridge().putEvents(
+  new PutEventsCommand({
+    Entries: [
+      { Source: "orders.service", DetailType: "OrderPlaced", Detail: "{}" },
+    ],
+  }),
+);
+await simAws.backgroundTasksComplete();
+
+const { Messages } = await simAws
+  .sqs()
+  .receiveMessage(
+    new ReceiveMessageCommand({ QueueUrl, MessageAttributeNames: ["All"] }),
+  );
+
+console.log(Messages?.[0]?.MessageAttributes?.["ERROR_CODE"]?.StringValue);
+// "NO_RESOURCE"
+```
+
+The message body is the event, as JSON. Its attributes are the ones EventBridge documents.
+`RULE_ARN` and `TARGET_ARN` name where the event was going. `ERROR_CODE` and `ERROR_MESSAGE` say why
+it failed, and `RETRY_ATTEMPTS` counts the retries made. `EXHAUSTED_RETRY_CONDITION` is
+`MaximumRetryAttempts` or `MaximumEventAgeInSeconds` when a retry limit ran out.
+
+`ERROR_CODE` is `NO_PERMISSIONS` for a target that refused EventBridge and `NO_RESOURCE` for one
+that is not there. Every other failure is `ERROR_FROM_TARGET`. EventBridge lists these codes
+without saying which failure gets which.
+
+A missing target and a refusal are never retried, because the same request gets the same answer.
+EventBridge sends both straight to the dead-letter queue, and so does Yulin. Any other failure is
+retried on the simulation's clock. The first retry is due one second after the failed attempt, and
+each following wait doubles to 2, 4, 8 seconds and so on. Retries stop at `MaximumRetryAttempts`, or
+once the event is `MaximumEventAgeInSeconds` old. A retry only runs as `advanceBy(...)` moves the
+clock past it.
+
+EventBridge sends to the dead-letter queue as `events.amazonaws.com`, with the rule ARN as
+`aws:SourceArn`, so the queue policy has to admit it. A dead-letter queue that is missing or refuses
+EventBridge leaves the failure in `deliveryFailures`. An event that reached its dead-letter queue
+leaves nothing there.
+
+A Lambda target is invoked asynchronously. Once Lambda accepts the invocation the delivery is done,
+and a handler error is left to the function's own retries and destinations.
+
 ## Permissions
 
 Most operations are authorized by simulated IAM against the bus ARN. The two that name no bus
@@ -1048,6 +1252,8 @@ no permission for.
 ## Supported operations
 
 - `CreateEventBus`, `DeleteEventBus`, `DescribeEventBus`, `ListEventBuses` and `PutEvents`.
+- Partner event buses created with `EventSourceName`, and `DescribeEventSource`. A test acts as the
+  partner through `addPartnerEventSource(...)` and `putPartnerEvents(...)`.
 - `PutRule`, `DeleteRule`, `DescribeRule`, `ListRules`, `EnableRule`, `DisableRule` and
   `TestEventPattern`.
 - Scheduled rules, with a `rate(...)` or six-field `cron(...)` `ScheduleExpression`, fired by
@@ -1061,6 +1267,8 @@ no permission for.
 - Targets in another account or region of the same simulation, admitted by the target's own resource
   policy on `aws:SourceArn` or `aws:SourceAccount`, as real EventBridge does.
 - A target's fixed `Input`, and `deliveryFailures` for a delivery that failed.
+- A target's `RetryPolicy`, retried on the simulation's clock, and its `DeadLetterConfig`, with the
+  dead-letter message attributes EventBridge documents.
 - The `default` bus in every account and region, without one being created.
 - Bus descriptions, creation timestamps from the simulation's clock, and prefix-narrowed paged
   listings.
@@ -1073,9 +1281,13 @@ no permission for.
 
 - Targets deliver to Lambda, SQS and SNS, and run a task in ECS. A target ARN naming any other
   service is refused as the target is added, ahead of any matching event.
-- Target `InputPath` and `InputTransformer` are refused, as are dead letter queues and retry
-  policies. A delivery is attempted once. A target `RoleArn` is refused except on an ECS target.
-  That is the one target type that runs as a role, where the others run as the service principal.
+- Target `InputPath` and `InputTransformer` are refused. A target `RoleArn` is refused except on an
+  ECS target. That is the one target type that runs as a role, where the others run as the service
+  principal.
+- A target with no `RetryPolicy` is delivered once. Real EventBridge retries such a target for up to
+  24 hours and 185 times. Retry waits are deterministic powers of two seconds, where real
+  EventBridge uses exponential backoff with jitter. The fixed sequence lets a test move the clock to
+  a known retry.
 - An ECS target's `EcsParameters` takes `TaskDefinitionArn` and `TaskCount`, and takes and ignores
   `LaunchType`, `PlatformVersion`, `NetworkConfiguration` and `CapacityProviderStrategy`, since
   there is no placement and no network here for them to apply to. Anything else it can carry, such
@@ -1115,8 +1327,13 @@ no permission for.
   attribute are all missing, and a caller from another account cannot be admitted to a bus. That is
   stricter than real AWS.
 - Putting an event onto another account's or region's bus is refused.
-- Partner event buses and partner event sources are refused, as are event bus tags, encryption with
-  a customer managed key, dead letter queues, logging configuration and global endpoints. An
-  `AWS::Events::EventBus` carrying `Tags` deploys with the tags dropped and the property recorded.
+- Event bus tags, encryption with a customer managed key, dead letter queues, logging configuration
+  and global endpoints are refused. An `AWS::Events::EventBus` carrying `Tags` deploys with the tags
+  dropped and the property recorded.
+- A pending partner event source never expires, and `DescribeEventSource` leaves out
+  `ExpirationTime`. Its `CreatedBy` is the segment after `aws.partner/`, such as `stripe.com`.
+  `ListEventSources`, `ActivateEventSource` and `DeactivateEventSource` are absent, as are the
+  partner's own commands. A partner is a test calling `addPartnerEventSource(...)` and
+  `putPartnerEvents(...)`.
 - Archives, replay, schema registry and discovery, API destinations and connections are not
   simulated.

package/docs/services/scheduler/README.md

@@ -303,6 +303,64 @@ regardless of `ActionAfterCompletion`.
 enabling it picks up from the next due instant. What it missed is never replayed. An update that
 changes the expression reschedules from the new one.
 
+### Flexible time windows
+
+`FlexibleTimeWindow: { Mode: "FLEXIBLE", MaximumWindowInMinutes: n }` delays each invocation by up
+to `n` minutes. The schedule still falls due at the times its expression gives. Each occurrence then
+invokes its target at a moment drawn inside `[due, due + n minutes)`. The moment is never before the
+due time and always before the window closes.
+
+The draw is made separately for every occurrence. A test that advances the clock past the end of an
+occurrence's window sees exactly one invocation for it, whatever was drawn. A test that stops inside
+the window may or may not see it. Assert after the window has closed.
+
+The draws come from the `random` source the `SimAws` was built with. It defaults to the host's
+`Math.random`, and the moments differ from run to run. Pass a `SimSeededRandom` to draw the same
+moments every time (to reproduce a failure, for example).
+
+```typescript sim-scheduler-flexible-window
+/**
+ * A schedule invoking its target up to fifteen minutes after each hour.
+ */
+
+import {
+  CreateScheduleCommand,
+  GetScheduleCommand,
+} from "@aws-sdk/client-scheduler";
+
+import { SimAws, SimSeededRandom } from "@kensio/yulin";
+
+// The same seed draws the same invocation moments on every run.
+const simAws = new SimAws({ random: new SimSeededRandom(2026) });
+
+await simAws.scheduler().createSchedule(
+  new CreateScheduleCommand({
+    Name: "hourly-digest",
+    ScheduleExpression: "cron(0 * * * ? *)",
+    FlexibleTimeWindow: { Mode: "FLEXIBLE", MaximumWindowInMinutes: 15 },
+    Target: {
+      Arn: "arn:aws:lambda:us-east-1:888888888888:function:digest",
+      RoleArn: "arn:aws:iam::888888888888:role/SchedulerRole",
+    },
+  }),
+);
+
+const described = await simAws
+  .scheduler()
+  .getSchedule(new GetScheduleCommand({ Name: "hourly-digest" }));
+
+console.log(described.FlexibleTimeWindow);
+// { Mode: "FLEXIBLE", MaximumWindowInMinutes: 15 }
+```
+
+A `FLEXIBLE` window needs `MaximumWindowInMinutes`, a whole number from 1 to 1440. An `OFF` window
+must leave it out. Either mistake is a `ValidationException`. `GetSchedule` reports the window the
+schedule was created with.
+
+A schedule deleted or replaced while an occurrence is waiting inside its window does not invoke for
+that occurrence. A one-time schedule with `ActionAfterCompletion: "DELETE"` is removed once its
+delayed invocation has been made.
+
 ## Running an ECS task on a schedule
 
 A target whose ARN names an ECS cluster runs a [simulated ECS](https://yulinsim.dev/services/ecs/)
@@ -812,6 +870,8 @@ Resources of the same stack.
   authorized against that role's own policies. Lambda targets use asynchronous Event invocation.
 - ECS targets, running a simulated task as the execution role, with the task definition and
   `TaskCount` from `EcsParameters` and container overrides from the target's `Input`.
+- `FlexibleTimeWindow` in both modes, with each `FLEXIBLE` invocation drawn inside its window from
+  the simulation's `random` source.
 - `ActionAfterCompletion`, and `deliveryFailures` for invocations that did not happen.
 - Target retry policies driven by simulated time, and standard SQS dead-letter queues carrying the
   original input and Scheduler diagnostic attributes.
@@ -829,8 +889,8 @@ Resources of the same stack.
 
 - A schedule only fires while a test advances the simulation's clock. The host's clock drives none
   of it, and a simulation left alone in real time never fires however long it is left.
-- Firing is exact and exactly once. Real Scheduler invokes within a minute of the due time, and its
-  promise is at-least-once.
+- Firing is exact and exactly once with the window `OFF`. Real Scheduler invokes within a minute of
+  the due time, and its promise is at-least-once.
 - Retry delays are deterministic powers of two seconds. Real Scheduler uses exponential backoff
   without publishing an exact sequence. The fixed sequence lets a test advance to a known retry
   instant.
@@ -844,9 +904,12 @@ Resources of the same stack.
   real Scheduler holds the group in `DELETING` until they have gone.
 - The `default` schedule group cannot be deleted. AWS leaves the answer to that request
   undocumented.
-- `FlexibleTimeWindow` with `Mode: "FLEXIBLE"` is refused. Real Scheduler invokes the target at an
-  unpredictable moment inside the window, and firing at the exact due time instead would let a test
-  rely on timing AWS leaves unpromised.
+- A flexible window draws each invocation moment uniformly, to the millisecond. AWS documents only
+  that the target is invoked inside the window after the scheduled time, and publishes no
+  distribution.
+- The wording of the refusals for a `FLEXIBLE` window with no `MaximumWindowInMinutes`, and an `OFF`
+  window with one, is Yulin's own. AWS refuses both and does not document the message. The range
+  refusals use the API's constraint wording.
 - `ScheduleExpressionTimezone` is read from the host's own timezone data through `Intl`, so a zone
   the host has never heard of is refused even where AWS would take it. A schedule that names none
   runs in UTC.

package/docs/time/README.md

@@ -247,6 +247,24 @@ Yulin uses the clock for:
 - `Date`, global timers, and invocation deadlines inside a simulated Lambda invocation
 - HTTP response `Date` headers
 
+## Values AWS leaves to chance
+
+Some AWS behaviour is unpredictable by design. An EventBridge Scheduler
+[flexible time window](https://yulinsim.dev/services/scheduler/#flexible-time-windows) invokes its
+target at a moment AWS chooses inside the window. Yulin draws those values from the `random` option
+of `SimAws`, which defaults to the host's `Math.random`.
+
+Pass a `SimSeededRandom` to draw the same values on every run:
+
+```typescript
+import { SimAws, SimSeededRandom } from "@kensio/yulin";
+
+const simAws = new SimAws({ random: new SimSeededRandom(2026) });
+```
+
+A test that advances the clock past the end of a window passes whatever was drawn. A seed is for
+reproducing a run (one that failed, for example).
+
 ## Limitations
 
 - Scheduled [EventBridge rules](https://yulinsim.dev/services/eventbridge/#rules-that-fire-on-a-schedule)