@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/ecr/README.md

@@ -1,31 +1,20 @@
 # Simulated ECR
 
-Yulin includes a simulated Amazon ECR for tests and local development. It holds repositories, and
-each repository holds images by tag, where a simulated image is a real in-process handler.
-
-That is what this service is for. A container image Lambda function cannot run here, because Yulin
-never reads an image, so something has to say what the code inside that image actually is. A
-repository is the natural place to say it. It is the stable name for the thing that holds the code,
-outliving any tag and any CDK construct ID, and a repository holding a registered handler outlives
-the stack that declared it too.
+Yulin represents an ECR image with an in-process Lambda handler. Register the handler against a
+repository and tag, then deploy or create a container image function that uses the image URI.
 
 ECR-specific types are imported from the `@kensio/yulin/ecr` subpath.
 
 ## What a simulated image is
 
-An image URI is only ever an identifier here. No image is pulled or inspected, and no layer,
-manifest, digest or scan finding exists. A simulated image is a handler function, registered against
-a repository and a tag.
+An image URI identifies a registered handler. Image content remains outside the simulation.
 
-Registering one is a Yulin-native operation, named `simulateImage` to keep it clear of a simulated
-`PutImage`. Real `PutImage` takes an image manifest for layers that were pushed over the Docker
-registry protocol. None of that happens in this process, and a simulated `PutImage` would be a
-command taking an argument nothing could produce.
+Use the Yulin-specific `simulateImage` method to register a handler. The simulated surface has no
+ECR SDK or Docker registry operations.
 
 ## Registering a handler as an image
 
-Register the handler once, in test setup, and every function that runs an image from that repository
-is created from it.
+Register the handler during test setup. Lambda resolves image functions from the same repository.
 
 ```typescript sim-ecr-register-image
 /**
@@ -82,36 +71,22 @@ console.log(Buffer.from(output.Payload).toString());
 await simAws.backgroundTasksComplete();
 ```
 
-Naming a repository is what creates it. A repository holds only its images. There is no prior
-declaration to make, and a test can name the repository its templates already point at.
+Calling `repository(name)` creates the repository if it is absent.
 
-The repository takes a bare name such as `orders` or `platform/orders`, and never a full image URI.
-The account, the region and the registry host around it come from the simulated ECR the repository
-belongs to. A name real ECR would refuse is refused here too.
+Pass a repository name such as `orders` or `platform/orders`. The selected simulated account and
+Region supply the registry host.
 
 ## How an image URI is matched
 
-Resolving an image URI happens in two steps, and the tag means something different in each.
-
-Finding the repository ignores the tag. A function's `Code.ImageUri` is matched on the registry host
-and the repository name, with any tag or digest dropped, because no tag is stable enough to write
-into a test. A CDK image asset is tagged with the asset content hash, which changes whenever the
-image source does, and a pipeline-built image is usually tagged with a git sha or a build number
-passed in as a stack parameter. An `ImageUri` built by `Fn::Sub` or from a stack parameter is
-matched on what it resolves to.
+Yulin first matches the registry host and repository name. It then looks for the requested tag. A
+registered tag selects that handler. An unknown tag, a digest or no tag selects the most recently
+registered handler. This fallback lets content-hash and build-number tags resolve without copying
+those generated values into the test.
 
-Choosing the image in that repository does read the tag. A tag the repository holds selects exactly
-that image, and any other tag, or none at all, falls back to the image registered most recently.
+The registry host determines the account and Region. Repositories with the same name in different
+scopes remain separate. Cross-account image references are supported.
 
-The registry host is part of the match, and the account and the region have to agree. A function can
-run an image from another account's repository, as it can on real AWS, and a same-named repository
-in another account is a different repository.
-
-So `orders:blue` runs the handler registered under `blue` where the repository holds one, and the
-handler registered most recently otherwise. That is how a blue/green pair of images in one
-repository can back two functions differently, while a content hash tag nobody registered still
-finds something to run. Registering a tag again both replaces what it held and makes it the most
-recent registration.
+Registering a tag again replaces its handler and makes that handler the most recent registration.
 
 ```typescript sim-ecr-image-tags
 /**
@@ -152,18 +127,15 @@ console.log(Buffer.from(output.Payload).toString()); // "blue handler"
 await simAws.backgroundTasksComplete();
 ```
 
-A function created directly through `CreateFunction` resolves its image the same way a template
-function does, as the example above shows. A function whose image resolves to no handler is refused,
-the way real Lambda refuses a function whose image it cannot pull.
+Direct `CreateFunction` calls and CloudFormation deployments use the same resolution rules. Lambda
+refuses an image URI that resolves to no handler.
 
 ## Repositories in CloudFormation
 
-`AWS::ECR::Repository` creates a simulated repository. A template declares a repository and never an
-image, as real CloudFormation does. A deployed repository starts empty unless a handler has already
-been registered in it.
+Simulated CloudFormation creates `AWS::ECR::Repository`. The repository starts empty unless a
+handler was already registered under its name.
 
-`Ref` returns the repository name, and `Fn::GetAtt` exposes `Arn` and `RepositoryUri`. An
-application stack can build its function's `ImageUri` from the repository a platform stack declared.
+`Ref` returns the repository name. `Fn::GetAtt` supports `Arn` and `RepositoryUri`.
 
 ```typescript sim-ecr-cloudformation-repository
 /**
@@ -236,34 +208,23 @@ console.log(Buffer.from(output.Payload).toString());
 await simAws.backgroundTasksComplete();
 ```
 
-A repository a handler is already registered in is adopted, and the order these happen in makes no
-difference. The image can exist before the stack that declares the repository, as it does in real
-life.
+A deployment adopts a repository that already contains a registered handler.
 
-Tearing the stack down removes the repository only where it holds no simulated image. One that does
-is left where it is, and the deletion is recorded as skipped, because the handler in it was
-registered outside any stack and is what every later deploy resolves to. Real ECR also refuses to
-delete a repository that still holds images, which fails the stack unless the template says
-`EmptyOnDelete`. Here the refusal is recorded and the teardown carries on, since what is being
-protected is a test's own registration.
+Stack teardown removes an empty repository. A repository containing a handler remains in place and
+its deletion is recorded as skipped. Teardown continues after the skipped deletion.
 
-Every other property a repository can declare is recorded as an ignored property, and the repository
-is created without it. That covers `ImageScanningConfiguration`, `ImageTagMutability`,
+Other repository properties are recorded as ignored. These include `ImageScanningConfiguration`, `ImageTagMutability`,
 `LifecyclePolicy`, `RepositoryPolicyText`, `EncryptionConfiguration`, `EmptyOnDelete` and `Tags`.
 
 ## Where a function's handler comes from
 
-Two things can back a container image function, and a deploy is looked at in this order:
+Yulin resolves a container image function in this order:
 
-1. An [executable binding](https://yulinsim.dev/services/lambda/#executable-bindings) given to that deploy, including one
-   naming the image repository. A binding is the more specific thing to have said, since it is about
-   one deploy.
-2. The simulated ECR repository the function's `Code.ImageUri` names. That is a standing statement
-   about what the image is, made once and good for every stack that runs it.
+1. An [executable binding](https://yulinsim.dev/services/lambda/#executable-bindings) supplied for the deployment.
+2. The handler registered in the ECR repository named by `Code.ImageUri`.
 
-A function with no binding and no registered image is skipped with a diagnostic, and the rest of the
-stack deploys. The reason separates a missing repository from an empty one, since those send you to
-different places. One is a wrong name, and the other is a handler that was never registered.
+A function with no binding or registered image is skipped. The diagnostic distinguishes a missing
+repository from a repository with no handlers.
 
 ## Available functionality
 
@@ -278,16 +239,14 @@ different places. One is a wrong name, and the other is a handler that was never
 
 ## Limitations
 
-Current documented limitations:
-
 - No image content, layer, digest, manifest or scan behaviour is simulated. A repository holds
   handlers, and no image is ever pulled or inspected.
 - There are no ECR SDK commands. `CreateRepository`, `DescribeRepositories`, `PutImage`,
   `DescribeImages`, `BatchDeleteImage` and `GetAuthorizationToken` are all absent. Registering an
   image is a Yulin-native operation because real `PutImage` takes a manifest for layers pushed over
   the Docker registry protocol, and that protocol never runs in this process.
-- Nothing authorizes against a repository. With no requests to authorize, a repository policy goes
-  unread and simulated IAM stays out of it.
+- CloudFormation authorizes `ecr:CreateRepository` and `ecr:DeleteRepository`. Handler registration
+  has no caller and skips authorization. Repository policies are ignored.
 - Lifecycle policies go unevaluated, and no simulated image ever expires. Tag mutability goes
   unenforced, and registering the same tag again replaces what it held.
 - Naming a repository creates it. There is no `CreateRepository` to fail for a name already taken,
@@ -295,8 +254,8 @@ Current documented limitations:
 - A stack teardown records the deletion of a repository holding a simulated image and carries on,
   where real CloudFormation fails the stack unless the template says `EmptyOnDelete`. The repository
   and its handler are left in place, and `EmptyOnDelete` itself goes unread.
-- Nothing tracks which stack created a repository. A repository holding no simulated image is
-  removed by the teardown of any stack that declared it, and made again by the next deploy.
+- The repository model records no owning stack. Teardown of any declaring stack removes an empty
+  repository.
 - Repository tags, registry policies, pull through cache rules, replication configuration and ECR
-  Public are not simulated.
-- ECR has no HTTP API under `serveSimAws`, and nothing for a Docker client to talk to.
+  Public are absent.
+- `serveSimAws` exposes no ECR HTTP API or Docker registry endpoint.

package/docs/services/ecs/README.md

@@ -1,31 +1,20 @@
 # Simulated ECS
 
-Yulin includes a simulated Amazon ECS for tests and local development. It holds clusters, task
-definitions and services in memory, runs tasks from handlers you bind to their containers, and
-authorizes every operation with simulated IAM.
+Yulin simulates ECS clusters, task definitions, tasks and services. It runs JavaScript or TypeScript
+handlers bound to container image URIs. Use `simAws.ecs()` directly or intercept an `ECSClient`.
+ECS types are available from `@kensio/yulin/ecs`.
 
-ECS-specific types are imported from the `@kensio/yulin/ecs` subpath.
+## Binding code to a container image
 
-## What Yulin does with a container image
+Yulin uses an image URI as an identifier for an in-process handler. It does not pull or execute the
+image. A container with a matching binding runs the handler. An unbound container is recorded as
+unsimulated while the rest of the task continues.
 
-Yulin never looks inside a container image, and it could not if it tried. An image may hold a Go
-binary, nginx, Redis or anything else, and the only thing Yulin can run is JavaScript or TypeScript
-in its own process.
+A task definition may include application and support containers. Yulin stores and reports every
+container, but only runs containers that have a binding.
 
-So an image URI is only ever an identifier. Nothing here reads it, pulls it, or runs anything from
-it. It is stored as declared, and it is what a container is matched on when a task runs, in the same
-way an image URI identifies a container image Lambda function. The rule that follows is that a
-container matched to a handler runs that handler, and a container with no match is recorded as not
-simulated while the rest of the task carries on.
-
-A realistic task definition holds an application container, a log router and an observability agent.
-Only the first of those is something Yulin could ever run, and all three are stored and reported
-back exactly as declared.
-
-The case this leaves out is a sidecar the application depends on, such as a Redis or a database in
-the same task. Point its connection details, which are ordinary environment variables, at a real one
-you run yourself. See [non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/) for how that fits
-together.
+Run required sidecars such as Redis separately and pass their connection details through environment
+variables. See [non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/).
 
 ## Registering a task definition
 
@@ -76,9 +65,7 @@ console.log(described.taskDefinition?.containerDefinitions?.[0]?.image);
 // "example.dkr.ecr.eu-west-2.amazonaws.com/checkout:1"
 ```
 
-Container definitions are stored as declared, whatever the image is and whether or not Yulin could
-ever run it. That covers port mappings, environment variables and secrets. A `valueFrom` naming a
-Secrets Manager secret is held as the identifier it is, and never resolved.
+Container definitions retain their images, port mappings, environment variables and secrets.
 
 A registration that declares something this simulation has no room for is refused outright, and
 never trimmed. That way a declaration cannot go missing from the revision it made.
@@ -132,9 +119,8 @@ a full task definition ARN. The ARN of a revision is
 
 ## Deregistering a revision
 
-`DeregisterTaskDefinition` marks one revision `INACTIVE` without removing it. It stays describable
-by `family:revision` and by ARN, because something already holding either of those still needs to
-find out what it declared. What it stops being is the revision the family resolves to.
+`DeregisterTaskDefinition` marks a revision `INACTIVE` without removing it. The revision remains
+available by `family:revision` or ARN, but the family name no longer resolves to it.
 
 ```typescript sim-ecs-deregister-task-definition
 /**
@@ -234,8 +220,8 @@ A family counts as inactive once every one of its revisions has been deregistere
 
 ## Clusters
 
-A cluster is a named scope for the tasks and services that will run in it. `CreateCluster`,
-`DescribeClusters`, `ListClusters` and `DeleteCluster` hold them.
+A cluster contains tasks and services. Use `CreateCluster`, `DescribeClusters`, `ListClusters` and
+`DeleteCluster` to manage it.
 
 ```typescript sim-ecs-clusters
 /**
@@ -290,13 +276,13 @@ A cluster is named either by its short name or by its full ARN, and the two are
 ARN belonging to another account or region names a different cluster. `DescribeClusters` reports it
 as a `MISSING` failure, and `DeleteCluster` refuses it.
 
-A cluster has to exist before a task can run in it, including the `default` one. Yulin creates no
-cluster on its own, so create the one the tasks run in.
+Create a cluster before running a task. This includes the `default` cluster, which Yulin does not
+create automatically.
 
 ## Running a task
 
-`bindContainer` says what a container runs. `RunTask` then starts a task in a cluster, and the bound
-handlers run in this process.
+`bindContainer` associates an image with a handler. `RunTask` starts the task and schedules bound
+handlers to run in process.
 
 ```typescript sim-ecs-run-task
 /**
@@ -376,9 +362,7 @@ The task stops with a `stopCode` of `TaskFailedToStart` saying that nothing ran.
 
 ### Binding by image repository
 
-A container built by CDK or by a pipeline has an image tag that changes with every build, so naming
-the container by hand is the wrong way round. A binding can name the repository instead, and the tag
-is ignored on both sides.
+Use a repository binding when image tags change between builds. Repository matching ignores the tag.
 
 ```typescript sim-ecs-bind-image-repository
 /**
@@ -505,9 +489,8 @@ Read inside the handler to get the container's own.
 
 ## The task role
 
-While a container runs, its AWS calls are attributed to the task definition's `taskRoleArn`, in the
-same way a sim Lambda function's are to its execution role. Calls made through an SDK client
-intercepted by `SimSdk` pick this up without the code under test knowing.
+AWS calls made by a container use the task definition's `taskRoleArn`. An SDK client intercepted by
+`SimSdk` picks up the role from the running handler.
 
 ```typescript sim-ecs-task-role
 /**
@@ -600,10 +583,8 @@ alone, since there is no image to pull and no log driver to write to.
 
 ## Container secrets
 
-A container definition's `secrets` are resolved when the task starts, from simulated Secrets Manager
-or simulated SSM Parameter Store according to what each `valueFrom` names, and the values appear in
-the container's environment alongside its declared `environment`. A handler reads them through
-`process.env` like anything else.
+Yulin resolves container `secrets` from simulated Secrets Manager or SSM Parameter Store when the
+task starts. The values appear in `process.env` alongside the declared environment variables.
 
 They are read as the task definition's `executionRoleArn` rather than its `taskRoleArn`. That is the
 split real ECS makes. The execution role is what the task agent pulls secrets with before a
@@ -765,8 +746,7 @@ is reported as it stands, keeping the reason it stopped for.
 
 ## Services
 
-A task runs and stops. A service keeps tasks running, and that is what a deployed application
-usually is. It is a named service in a cluster, running some number of tasks from a task definition.
+An ECS service maintains a desired number of tasks from one task definition in a cluster.
 
 `CreateService` creates one. Its tasks exist as soon as the request is answered and reach `RUNNING`
 on the simulation's background work, as real ECS brings a new service up. The service reports the

package/docs/services/elbv2/README.md

@@ -1,24 +1,16 @@
 # Simulated Elastic Load Balancing
 
-Yulin includes a simulated Application Load Balancer for tests and local development. Load
-balancers, target groups, listeners and listener rules are held in memory and every operation is
-authorized by simulated IAM. ELBv2-specific types are imported from the `@kensio/yulin/elbv2`
-subpath.
-
-A load balancer created here has a DNS name of the shape real ELB issues, and a
-[Route53](https://yulinsim.dev/services/route53/) record pointing at that name resolves to it. A request made to your own
-hostname reaches the load balancer as it would deployed. A request is matched to a listener by port
-and then to one of that listener's rules, and a `forward` action sends it to a target group, where a
-registered [Lambda](https://yulinsim.dev/services/lambda/) function is invoked with the request and its response becomes the
-HTTP response.
-
-Only the application load balancer is simulated. A network or gateway load balancer routes below
-HTTP, which nothing here speaks, and `Type: "network"` is refused outright.
-
-No TLS is performed anywhere in this. An HTTPS listener holds a certificate and is checked against
-simulated ACM, and everything travels in the clear. See
-[HTTPS listeners and certificates](#https-listeners-and-certificates) for what that leaves a test
-able to conclude.
+Yulin simulates Application Load Balancers, target groups, listeners and listener rules for tests
+and local development. Requests pass through the listener and rule configuration before reaching a
+registered Lambda function or simulated ECS service. Simulated IAM authorizes every operation.
+
+Each load balancer receives an AWS-shaped DNS name. A simulated
+[Route 53](https://yulinsim.dev/services/route53/) record can point a local hostname at that name, so
+an HTTP request follows the same routing path as the deployed application.
+
+Network and Gateway Load Balancers are not simulated. HTTPS listeners validate their certificates
+against simulated ACM, but Yulin does not perform TLS. Import ELBv2-specific types from
+`@kensio/yulin/elbv2`.
 
 ## Creating a load balancer
 
@@ -73,9 +65,8 @@ why a load balancer cannot be named starting with `internal-`.
 
 ## Target groups hold functions or addresses
 
-A target group names what it holds through its `TargetType`, and that decides the rest. It sets how
-many targets the group takes, what a target's `Id` has to look like, and whether the group carries a
-protocol and port at all.
+`TargetType` determines what a target group can contain. It controls the number and shape of target
+IDs, and whether the group requires a protocol and port.
 
 ```typescript sim-elbv2-lambda-target-group
 /**
@@ -178,15 +169,14 @@ console.log(health.TargetHealthDescriptions?.length); // 1
 console.log(health.TargetHealthDescriptions?.[0]?.Target.Port); // 8080
 ```
 
-`TargetType: "instance"` is refused outright, because there are no EC2 instances here for it to mean
-anything about. A group created as one would look configured and route nowhere. A request naming no
-target type at all is refused for the same reason, since real ELB defaults it to `instance`.
+`TargetType: "instance"` is unsupported because Yulin does not simulate EC2 instances. Omitting
+`TargetType` is also rejected because AWS would default it to `instance`.
 
 ## Listeners and the rules on them
 
-A listener answers on a port and holds the default actions for a request no rule claims. Rules carry
-a priority, and that is what decides which of several matching rules claims a request. Two rules on
-one listener cannot hold the same priority.
+A listener handles one port and provides the default action when no rule matches. When several
+rules match, the lowest priority number wins. Two rules on the same listener cannot use the same
+priority.
 
 ```typescript sim-elbv2-listener-rules
 /**
@@ -1761,7 +1751,7 @@ console.log(created.LoadBalancers?.[0]?.DNSName);
 // "shop-alb-0000000001.eu-west-2.elb.amazonaws.com"
 ```
 
-## Available functionality
+## Supported operations
 
 - `CreateLoadBalancer`, `DescribeLoadBalancers` and `DeleteLoadBalancer`, with a DNS name, ARN,
   canonical hosted zone id, scheme and state on every load balancer.

package/docs/services/eventbridge/README.md

@@ -1,12 +1,12 @@
 # Simulated EventBridge
 
-Yulin includes a simulated Amazon EventBridge for tests and local development. Event buses are held
-in memory and every operation is authorized by simulated IAM.
+Yulin simulates Amazon EventBridge event buses, rules, targets and `PutEvents` for tests and local
+development. Rules can match events, run on a simulated schedule, and deliver to simulated Lambda,
+SQS, SNS or ECS. Event buses and rules are stored in memory, and simulated IAM authorizes every
+operation.
 
-Event buses, rules, targets and `PutEvents`. A rule can send matched events to a simulated Lambda
-function, SQS queue or SNS topic, run a simulated ECS task, or fire on a schedule when a test
-advances simulated time. [EventBridge Scheduler](https://yulinsim.dev/services/scheduler/) is a separate service with its own
-docs. EventBridge-specific types are imported from the `@kensio/yulin/eventbridge` subpath.
+[EventBridge Scheduler](https://yulinsim.dev/services/scheduler/) is simulated separately. Import
+EventBridge-specific types from `@kensio/yulin/eventbridge`.
 
 ## Putting an event onto a bus
 
@@ -142,10 +142,8 @@ console.log(output.FailedEntryCount); // 0
 console.log(output.Entries?.[0]?.EventId !== undefined); // true
 ```
 
-This is real EventBridge behaviour, and not a gap here. AWS answers 200, finds no rule to match the
-event against, and drops it, without counting the entry as failed. A mistyped bus name therefore
-looks exactly like a working call. That is worth knowing before it costs an afternoon, and the
-simulation reproduces it faithfully.
+AWS also accepts and drops an event sent to a bus that does not exist. The entry is not counted as a
+failure, so check the bus name when `PutEvents` succeeds but no rule runs.
 
 ## Inspecting what a bus received
 
@@ -250,9 +248,8 @@ within the account. A rule ARN on the default bus is
 `arn:aws:events:<region>:<account>:rule/<name>`, and a rule on a custom bus carries the bus as well,
 as `rule/<bus>/<name>`.
 
-`PutRule` creates and updates alike, and an update **replaces** the rule rather than merging into
-it. A second request that leaves out the description clears the description. That is real behaviour
-and a common surprise.
+`PutRule` creates or updates a rule. An update replaces the stored rule instead of merging fields,
+so omitting the description clears it.
 
 `DisableRule` stops a rule matching, and `EnableRule` starts it again. A rule that was off picks up
 from the next event and leaves what it missed behind. `DeleteRule` on a rule that was never there
@@ -285,10 +282,9 @@ field, the pattern matches when the two lists overlap, and a pattern naming one
 event whose `resources` names several. `exists` is about the field and not its members, and a field
 carrying an empty list still exists.
 
-Anything else is refused at `PutRule`. The `cidr`, `equals-ignore-case`, `wildcard` and `$or`
-operators are all refused by name, as are the nested forms of `anything-but` and the
-case-insensitive forms of `prefix` and `suffix`. A pattern that silently matched nothing would look
-like a pattern that was simply too specific, and the rule would go unnoticed until the deployment.
+`PutRule` rejects unsupported operators instead of storing a pattern that can never match. These
+include `cidr`, `equals-ignore-case`, `wildcard`, `$or`, nested `anything-but`, and the
+case-insensitive forms of `prefix` and `suffix`.
 
 ## Testing a pattern without a rule
 
@@ -1049,7 +1045,7 @@ events across accounts that way, but nothing here can reach another simulation's
 treating a foreign ARN as local would let a test pass while the real call crossed a boundary it has
 no permission for.
 
-## Available functionality
+## Supported operations
 
 - `CreateEventBus`, `DeleteEventBus`, `DescribeEventBus`, `ListEventBuses` and `PutEvents`.
 - `PutRule`, `DeleteRule`, `DescribeRule`, `ListRules`, `EnableRule`, `DisableRule` and

package/docs/services/firehose/README.md

@@ -1,18 +1,16 @@
 # Simulated Kinesis Data Firehose
 
-Yulin includes a simulated Kinesis Data Firehose for tests and local development. A delivery stream
-takes records, buffers them, and writes them into a simulated S3 Bucket under the key format real
-Firehose uses. The records come from `PutRecord` or off a simulated Kinesis stream. A test can put an
-event and assert on the Object it landed in, without an AWS account and without waiting five minutes
-for a buffer to flush.
+Yulin simulates Kinesis Data Firehose delivery streams in memory. A stream accepts records directly
+or reads them from simulated Kinesis, buffers them, and writes each completed buffer to simulated S3.
+Advance simulated time to flush interval-based buffers without waiting in real time.
 
 Firehose specific types are imported from the `@kensio/yulin/firehose` subpath.
 
 ## Putting a record and finding the Object
 
-`simAws.firehose()` gives the service for the default account and region. A delivery stream needs a
-Bucket to write into and a Role to write as, so both exist before it does. Advancing the clock past
-the buffering interval is what delivers the buffer.
+`simAws.firehose()` returns Firehose for the default account and region. Create the destination
+bucket and delivery role before the delivery stream. Advance the clock past the buffering interval
+to write the buffered records.
 
 ```typescript sim-firehose-put-and-deliver
 /**
@@ -93,15 +91,13 @@ const { Contents } = await simAws
 console.log(Contents?.[0]?.Key);
 ```
 
-The put is answered straight away with a record id. The Bucket stays empty until the buffer is
-delivered. That delay is what a Firehose pipeline is built around.
+`PutRecord` returns a record ID immediately. The bucket remains empty until the buffer is delivered.
 
 ## Buffering
 
-A delivery stream holds its records until the buffer passes `SizeInMBs` or `IntervalInSeconds`,
-whichever comes first. Everything in one buffer arrives as one Object, with the records concatenated
-end to end. A producer that wants lines puts the newline on the end of each record. The example
-below does exactly that.
+A delivery stream flushes when it reaches `SizeInMBs` or `IntervalInSeconds`, whichever comes first.
+Firehose concatenates all records in the buffer into one S3 object. Add a newline to each record if
+the object should contain separate lines.
 
 `IntervalInSeconds` runs from the first record of a buffer. The default is 300 seconds and the
 default size is 5 MB, as they are on real Firehose.
@@ -224,8 +220,8 @@ the background scheduler, the way real Firehose answers the producer before it w
 
 ## The Object key
 
-The key is the `Prefix`, then the UTC date path, then the delivery stream name, its version, the
-delivery time and a random string:
+Object keys contain the configured `Prefix`, UTC date path, delivery stream name, version, delivery
+time, and a random suffix:
 
 ```
 <Prefix>YYYY/MM/DD/HH/<delivery-stream-name>-<version>-YYYY-MM-DD-HH-MM-SS-<random>
@@ -234,15 +230,15 @@ delivery time and a random string:
 A delivery stream with no `Prefix` gets the bare date path. The version is `1` and stays there,
 since a delivery stream's configuration is fixed once it is created.
 
-Simulated time is what the date path and the timestamp come from. A test that sets the clock to a
-known instant knows the prefix its Objects are under, and can list them.
+The date path and timestamp use simulated time. Set the clock before delivery to make the prefix
+predictable.
 
 ## Reading from a Kinesis stream
 
-A delivery stream can take its records off a simulated Kinesis stream instead. Create it with a
+A delivery stream can read records from simulated Kinesis. Create it with a
 `DeliveryStreamType` of `KinesisStreamAsSource` and a `KinesisStreamSourceConfiguration` naming the
-stream and the Role to read it as. Records put on the stream from then on are buffered and delivered
-the way put records are.
+stream and its read role. Records added after the delivery stream is created are buffered and sent
+to S3.
 
 ```typescript sim-firehose-kinesis-source
 /**
@@ -382,11 +378,8 @@ Creating a delivery stream hands Firehose the destination `RoleARN`, and the sou
 where it reads a Kinesis stream. `CreateDeliveryStream` authorizes `iam:PassRole` against each of
 them. See [passing a Role to a service](https://yulinsim.dev/services/iam/#passing-a-role-to-a-service) in the IAM docs.
 
-The delivery itself is a separate request, made as the delivery stream's `RoleARN`. The caller who
-put the record needs no S3 permission at all, and a Role that cannot write to the Bucket fails the
-delivery. Real
-Firehose answered that `PutRecord` minutes earlier, and what became of the buffer reaches the
-producer through CloudWatch. The simulator keeps the failure for a test to read instead.
+Delivery uses the delivery stream's `RoleARN`, not the identity that called `PutRecord`. The role
+needs `s3:PutObject` on the destination. Failed writes appear in `getDeliveryFailures()`.
 
 ```typescript sim-firehose-permissions
 /**
@@ -507,9 +500,8 @@ what a test checking the denial does. Anything else is also warned about on the
 `KinesisStreamSourceConfiguration` and `Tags` are read. A `Ref` gives the delivery stream name and
 `Fn::GetAtt` on `Arn` gives the ARN, the way real CloudFormation publishes them.
 
-A CDK `DeliveryStream` with an `S3Bucket` destination synthesizes that resource, along with the
-delivery Role and its policy. A CDK project reaches a simulated delivery stream by deploying its
-synthesized template, and nothing here has to be written by hand.
+A CDK `DeliveryStream` with an `S3Bucket` destination synthesizes this resource, its delivery role,
+and the role policy. Deploy that synthesized template directly into simulated CloudFormation.
 
 ```typescript sim-firehose-cloudformation
 /**
@@ -627,9 +619,9 @@ A `DeliveryStreamType` of `KinesisStreamAsSource` deploys as well. The
 `KinesisStreamSourceConfiguration` names the stream by ARN and the Role to read it as, and a stack
 declaring the stream beside the delivery stream archives what a producer puts on it.
 
-A delivery stream this simulation cannot deliver for is skipped and recorded in
-`stack.skippedResources`, and the rest of the stack deploys. That covers a destination other than
-S3, and a source property naming somewhere the records cannot come from, such as
+A delivery stream with an unsupported source or destination is recorded in
+`stack.skippedResources`, while the rest of the stack deploys. This includes destinations other than
+S3 and unsupported source properties such as
 `MSKSourceConfiguration` or `DatabaseSourceConfiguration`. The source property is what the skip is
 decided on, because a template that leaves `DeliveryStreamType` out gets `DirectPut` by default.