@kensio/yulin 1.21.6 → 1.21.8

package/docs/README.md

@@ -1,7 +1,42 @@
-# Simulated AWS usage documentation
+# Yulin documentation
 
-This directory contains area-specific documentation for Yulin. Each page explains the simulated
-behaviour and includes example code that can be copied into tests or local development scripts.
+Yulin runs simulated AWS services inside a Node.js process. Tests can use AWS SDK clients,
+CloudFormation templates, or direct service calls without connecting to AWS. Each `SimAws` instance
+holds its own state in memory.
+
+Yulin implements selected AWS behaviour. The service pages describe what each simulation supports
+and where it differs from AWS.
+
+## Install Yulin
+
+```bash
+npm install --save-dev @kensio/yulin
+```
+
+## Choose how to use Yulin
+
+Start with [test suite setup](https://yulinsim.dev/testing/) when adding Yulin to an application's
+tests. Create one simulated environment, deploy the application's infrastructure, and install SDK
+interception for the whole suite. Tests then use that shared environment as they would use an AWS
+account or a container-based simulator. Put the smaller set of tests that control simulated time in
+an isolated group because the clock belongs to the environment too.
+
+Start with [AWS SDK interception](https://yulinsim.dev/sdk/) when the code under test already uses an
+AWS SDK client. Yulin intercepts the client's `send` calls and returns responses from a simulated
+service. The application code continues to use the AWS SDK normally.
+
+Use [event factories](https://yulinsim.dev/factories/) when a test calls a handler directly and only
+needs an AWS event object. The factories fill in fields that the test does not care about.
+
+Use [CloudFormation](https://yulinsim.dev/services/cloudformation/) to build a simulation from a
+template. This also works with templates synthesized by AWS CDK and AWS SAM.
+
+Use the [localhost server](https://yulinsim.dev/serve/) when the code runs in another process or
+sends HTTP requests. The [AWS CLI guide](https://yulinsim.dev/cli/) explains how to point AWS CLI
+commands at the same endpoint.
+
+Read [simulated time](https://yulinsim.dev/time/) when a test needs to advance a schedule, expire a
+credential, or run other work that depends on time passing.
 
 ## Service documentation
 
@@ -42,7 +77,7 @@ behaviour and includes example code that can be copied into tests or local devel
 - [STS](https://yulinsim.dev/services/sts/ "Simulated STS usage docs")
 - [WAFv2](https://yulinsim.dev/services/wafv2/ "Simulated WAFv2 usage docs")
 
-## Feature documentation
+## Feature guides
 
 - [AI skill](https://yulinsim.dev/ai-skill/ "Yulin AI skill usage docs")
 - [The AWS CLI](https://yulinsim.dev/cli/ "The AWS CLI against simulated AWS usage docs")
@@ -52,4 +87,5 @@ behaviour and includes example code that can be copied into tests or local devel
 - [Non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/ "Dependencies Yulin does not simulate usage docs")
 - [Serving on localhost](https://yulinsim.dev/serve/ "Serving simulated AWS on localhost usage docs")
 - [Simulated time](https://yulinsim.dev/time/ "Simulated time usage docs")
+- [Test suite setup](https://yulinsim.dev/testing/ "Sharing one Yulin environment across a test suite")
 - [Terraform](https://yulinsim.dev/terraform/ "Deploying Terraform into simulated AWS usage docs")

package/docs/ai-skill/README.md

@@ -1,69 +1,72 @@
-# AI skill
+# AI skill for Yulin
 
-Yulin has an AI skill that teaches a coding agent how to test AWS code with the simulator well. It
-is `yulin-aws-simulation`, a `SKILL.md` written to the
-[Agent Skills specification](https://agentskills.io/specification) and installable into Claude Code,
-Codex CLI, Cursor, VS Code and anything else that reads one. It covers the part that lives outside
-the API.
+The `yulin-aws-simulation` skill gives coding agents instructions for using Yulin in tests and local
+development.
 
-These docs and the skill answer different questions. A page here says what a simulated service does
-and what its commands take. The skill says what to do with that. An AI agent reaching for Yulin
-without it tends to build a harness around the simulator, leave hand-rolled stubs in place beside
-it, or write an `instanceof` check against an SDK exception class that passes in production and
-fails against the simulation.
+## Install the skill
 
-## Install
+Install it in the current project's `.agents/skills/` directory:
 
 ```bash
 npx @kensio/skills add yulin-aws-simulation
 ```
 
-That copies the skill into `.agents/skills/`, the directory Codex CLI, Cursor, VS Code and Gemini
-CLI read. `--agent claude` puts it in `.claude/skills/`, and `--user` installs it under your home
-directory for every project.
+Codex CLI, Cursor, VS Code, and Gemini CLI read skills from that directory. To install the skill for
+Claude Code, add `--agent claude`. Add `--user` to install it for every project under your user
+account.
 
-As a Claude Code plugin:
+Claude Code can also install the skill from the Kensio plugin marketplace:
 
 ```bash
 claude plugin marketplace add KensioSoftware/kensio.ai
 claude plugin install yulin-aws-simulation@kensio
 ```
 
-It is also on npm as `@kensio/yulin-aws-simulation`, and every
-[kensio.ai release](https://github.com/KensioSoftware/kensio.ai/releases) carries it as a zip for a
-machine with no registry reach.
-
-## What it covers
-
-- Using `SimAws` and `SimSdk` directly, and spotting the helper class or `setupSimulatedAws()`
-  wrapper that starts to grow around them.
-- One synthesized CDK template behind the tests, the dev server and production, deployed with
-  `deployTemplateFile` or `deployCdkOut`.
-- When to register a resource at a chosen id, and when to deploy the stack that creates it.
-- Interception over hand-rolled stubs, down to the requests a fake accepts and the simulation
-  refuses.
-- Freezing the clock, then advancing it on purpose.
-- Assertions that read the simulation back.
-- Why service errors match by `name` and not by `instanceof`.
-- Deploying an expensive stack once per test file.
-- Running a handler as a real simulated Lambda, under its execution role, its declared environment
-  and its own log group.
-- Refusals as a feature, and gaps raised upstream.
-
-## Reading the API alongside it
-
-The skill sends the AI agent to these docs for anything API-shaped, and
-[llms.txt](https://yulinsim.dev/llms.txt) is the index it uses. Every page here is available as
-plain markdown by appending `llms.txt` to its URL, one file per guide and one per simulated service.
-That index works with or without the skill installed.
-
-The same pages ship inside the package. An installed project holds them under
-`node_modules/@kensio/yulin/docs/`, indexed by `node_modules/@kensio/yulin/llms.txt`, and they
-document the version in that package rather than the current release. An agent with no network
-reach has them, and so does one working on a project held a few versions back. Ripgrep and most
-editor search skip `node_modules` by default. An agent finds these files when something names the
-path for it.
-
-The skill lives at
-[kensio.ai/skills/yulin-aws-simulation](https://kensio.ai/skills/yulin-aws-simulation), versioned
-separately from Yulin and licensed Apache-2.0.
+The skill is also published as the `@kensio/yulin-aws-simulation` npm package. Each
+[kensio.ai release](https://github.com/KensioSoftware/kensio.ai/releases) includes a zip archive for
+installations that cannot reach a package registry.
+
+## What the skill teaches
+
+The skill tells an agent how to:
+
+- use `SimAws` and `SimSdk` directly
+- deploy the same synthesized CDK template in tests and local development
+- choose between deploying a resource and registering one directly
+- intercept AWS SDK clients without keeping separate hand-written stubs
+- control simulated time
+- inspect simulated state in assertions
+- match simulated service errors by `name`
+- share one simulated deployment and SDK interception across a whole test suite
+- give tests that control simulated time their own isolated Yulin environment
+- invoke code through a simulated Lambda function with its configured role and environment
+- treat unsupported behaviour as a gap to report, not behaviour to guess
+
+The [test suite setup guide](https://yulinsim.dev/testing/) states the default explicitly. An agent
+should set Yulin up once for the suite and let tests share it as they would share an AWS account or a
+container-based simulator. Tests that move the shared simulated clock are the main exception.
+
+## Give the agent access to the API docs
+
+The skill covers testing choices. The service guides document Yulin's APIs and supported AWS
+behaviour.
+
+The skill points agents to [yulinsim.dev/llms.txt](https://yulinsim.dev/llms.txt). That file indexes
+plain Markdown versions of every guide on the documentation site. Append `llms.txt` to a page URL to
+read that page as Markdown.
+
+The npm package includes the same documentation under `node_modules/@kensio/yulin/docs/`. Its index
+is `node_modules/@kensio/yulin/llms.txt`. These files match the installed Yulin version and remain
+available without network access. Some search tools skip `node_modules` unless the path is given
+explicitly.
+
+## Limitations
+
+- The skill does not replace the service guides. An agent still needs the relevant guide when it
+  works with a service command, event shape, or limitation.
+- The skill is versioned separately from Yulin. The documentation included in the installed Yulin
+  package is the reference for that package version.
+
+The skill source is available at
+[kensio.ai/skills/yulin-aws-simulation](https://kensio.ai/skills/yulin-aws-simulation) under the
+Apache-2.0 licence.

package/docs/cli/README.md

@@ -1,15 +1,11 @@
-# AWS CLI
+# Use the AWS CLI with Yulin
 
-The real `aws` CLI reaches a served simulated environment over a local endpoint URL, and twenty of
-Yulin's twenty-five SDK-facing services answer it.
+Point the AWS CLI at a served `SimAws` instance to run supported commands against simulated AWS.
 
-[Serving on localhost](https://yulinsim.dev/serve/) is the reference for what each service serves. This page
-covers the way in from a shell.
+## Start a local endpoint
 
-## An endpoint and a key to sign with
-
-Serving binds a simulated environment to a port. A served request runs as whoever signed it, and the
-access key to sign the first one comes from simulated IAM in the process that built the environment:
+Create an IAM user and access key in the simulation, then pass the same `SimAws` instance to
+`serveSimAws`:
 
 ```typescript sim-cli-endpoint
 /**
@@ -53,12 +49,11 @@ console.log(
 console.log(`export AWS_DEFAULT_REGION=${simAws.defaultRegionName}`);
 ```
 
-Pin the port when the URL has to stay the same between runs. Without one the server takes whatever
-is free.
+Set `port` when scripts need a stable endpoint. If you omit it, Yulin chooses an available port.
 
-## Configuring the CLI
+## Configure the CLI
 
-Four environment variables are the whole configuration:
+Export the endpoint, simulated credentials, and Region printed by the setup script:
 
 ```bash
 export AWS_ENDPOINT_URL=http://localhost:8787
@@ -67,8 +62,8 @@ export AWS_SECRET_ACCESS_KEY=RzIvKRp1sd5yXfEifA1twsUTd4GlHL5JpzvECpox
 export AWS_DEFAULT_REGION=us-east-1
 ```
 
-`sts get-caller-identity` is the call to check the wiring with. It reports the principal behind the
-key that signed the request:
+Run `sts get-caller-identity` to check the connection. It returns the simulated principal that owns
+the access key:
 
 ```bash
 aws sts get-caller-identity
@@ -79,16 +74,15 @@ aws sts get-caller-identity
 }
 ```
 
-The credentials have to come from simulated IAM. Any other key is refused with `403 Forbidden`, and
-an unsigned request reaches nothing.
+The credentials must come from simulated IAM. Yulin rejects an unknown key with `403 Forbidden`.
+It also rejects unsigned AWS API requests.
 
-A Region is required, as it is against real AWS. Changing it moves the CLI between simulated
-Regions, and a Queue created under `eu-west-2` is invisible to `AWS_DEFAULT_REGION=us-east-1`.
+A Region is required. Changing `AWS_DEFAULT_REGION` selects another simulated Region. For example,
+a queue created in `eu-west-2` is absent from `us-east-1`.
 
-### A named profile instead
+### Use a named profile
 
-A profile in the CLI's own config file carries the same four values. The simulation then stays out
-of the ambient environment:
+You can put the endpoint and credentials in the AWS CLI config:
 
 ```ini
 [profile sim]
@@ -98,12 +92,12 @@ aws_access_key_id = AKIAVEXOWARWMKBOA0MP
 aws_secret_access_key = RzIvKRp1sd5yXfEifA1twsUTd4GlHL5JpzvECpox
 ```
 
-`aws --profile sim sts get-caller-identity` then reaches the simulation while a bare `aws` still
-goes to real AWS. The profile has to carry credentials of its own. Once `--profile` is given the CLI
-stops reading `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` from the environment.
+Now `aws --profile sim sts get-caller-identity` reaches Yulin. The profile must contain its own
+credentials because the CLI stops reading `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` after you
+pass `--profile`.
 
-`role_arn` and `source_profile` work too. The CLI assumes the simulated Role for itself and signs
-with the session it gets back:
+Profiles with `role_arn` and `source_profile` also work. The CLI calls simulated STS and signs later
+requests with the returned role session:
 
 ```ini
 [profile reader]
@@ -113,10 +107,10 @@ role_arn = arn:aws:iam::888888888888:role/Reader
 source_profile = sim
 ```
 
-## Building the rest of the identities from the shell
+## Create more simulated identities
 
-Only the first key has to come from the process that built the simulation. `aws iam` builds
-everything after it:
+Only the first access key needs to come from the setup process. Use `aws iam` to create more users
+and keys through the endpoint:
 
 ```bash
 aws iam create-user --user-name shopper
@@ -125,8 +119,8 @@ aws iam put-user-policy --user-name shopper --policy-name read-buckets \
 aws iam create-access-key --user-name shopper
 ```
 
-`create-access-key` answers with the secret once. Signing with the new key reports the new User, and
-simulated IAM authorizes every request against the policy it was given:
+`create-access-key` returns the secret once. Requests signed with the new key run as the new user and
+are checked against its simulated IAM policies:
 
 ```bash
 aws s3api create-bucket --bucket nope
@@ -136,8 +130,8 @@ arn:aws:iam::888888888888:user/shopper is not authorized to perform: s3:CreateBu
 arn:aws:s3:::nope
 ```
 
-`aws sts assume-role` answers with temporary credentials. Export the three values it returns and the
-rest of the session runs as the Role:
+`aws sts assume-role` returns temporary credentials. Export the access key, secret key, and session
+token to run later commands as the role:
 
 ```bash
 aws sts assume-role --role-arn arn:aws:iam::888888888888:role/Reader --role-session-name probe
@@ -146,17 +140,12 @@ export AWS_SECRET_ACCESS_KEY=jm2N56vfVtLgJEo11OtbIXbgnJBgxpUMrszPrQdl
 export AWS_SESSION_TOKEN=11568oBDksY9czECUMiAWk9tzmvG7zlQNjtLI1WmhZFS...
 ```
 
-The expiry is stamped from the simulation's own clock, and
-[advancing it](https://yulinsim.dev/time/) past the expiry stops the session authenticating.
-
-## What answers
+The credentials expire according to [simulated time](https://yulinsim.dev/time/). Requests fail once
+the `SimAws` clock passes their expiry.
 
-Twenty simulated services answer the endpoint. S3, STS, IAM, ELBv2, SNS, CloudFormation and Lambda,
-along with the AWS JSON protocol services: DynamoDB, DynamoDB Streams, SQS, Cognito Identity
-Provider, EventBridge, ECS, SSM, ACM, CloudWatch, CloudWatch Logs, KMS, Secrets Manager and
-Rekognition.
+## Run service commands
 
-A quick tour of the ones a shell reaches for most:
+Use ordinary AWS CLI commands after the endpoint is configured:
 
 ```bash
 aws s3 cp ./index.html s3://widgets/index.html
@@ -168,16 +157,12 @@ aws secretsmanager get-secret-value --secret-id shop/db --query SecretString --o
 aws logs describe-log-groups --query 'logGroups[].logGroupName' --output text
 ```
 
-`--query`, `--output text` and the rest of the CLI's own machinery work throughout, because they run
-client-side over an ordinary AWS response.
+Client-side CLI options such as `--query` and `--output text` work with simulated responses.
 
-[The serve docs](https://yulinsim.dev/serve/#which-services-answer) list the operations each service
-implements. Anything outside those lists is refused as `NotImplemented`.
+The [localhost server guide](https://yulinsim.dev/serve/#which-services-answer) lists the operations
+available for each service. Yulin returns `NotImplemented` for other operations.
 
-## CLI traps
-
-Each of these is CLI behaviour, and each catches people out against real AWS too. They are collected
-here because a simulated endpoint is often where someone meets them first.
+## Commands that need extra configuration
 
 ### `--payload` needs `--cli-binary-format`
 
@@ -189,7 +174,7 @@ aws lambda invoke --function-name orders --payload '{"id":1}' out.json
 aws: [ERROR]: Invalid base64: "{"id":1}"
 ```
 
-Pass `--cli-binary-format raw-in-base64-out` and the same call runs the function:
+Pass `--cli-binary-format raw-in-base64-out` to send the JSON payload:
 
 ```bash
 aws lambda invoke --function-name orders --payload '{"id":1}' \
@@ -197,22 +182,21 @@ aws lambda invoke --function-name orders --payload '{"id":1}' \
 cat out.json
 ```
 
-`--invocation-type Event` answers `202` and runs the handler on the background scheduler. A script
-reading what the function did waits on `simAws.backgroundTasksComplete()` first.
+`--invocation-type Event` returns `202` before the handler runs. Code in the server process can call
+`simAws.backgroundTasksComplete()` before inspecting the result.
 
 ### S3 addressing style
 
-The CLI needs nothing here. Its default `auto` style sends path-style requests to a custom endpoint,
-which is what this endpoint routes. An SDK client is the one that needs `forcePathStyle: true`.
+The CLI's default `auto` addressing style sends path-style requests to custom endpoints. Yulin
+supports that form. AWS SDK clients need `forcePathStyle: true` when they use the served endpoint.
 
-Forcing `addressing_style = virtual` in the config file breaks it. The Bucket moves into a hostname
-the endpoint has no route for, and `list-objects-v2` comes back empty while `head-object` comes back
-`404`.
+Do not set `addressing_style = virtual` for the CLI profile. Yulin does not route virtual-hosted S3
+API requests through the general endpoint.
 
 ### `aws cloudformation deploy` uses change sets
 
-`deploy` is a CLI-side wrapper over `CreateChangeSet`, and simulated CloudFormation implements four
-operations that do not include it:
+The CLI implements `aws cloudformation deploy` with change sets. Yulin does not serve
+`CreateChangeSet`, so the command fails:
 
 ```bash
 aws cloudformation deploy --stack-name site --template-file template.json
@@ -221,26 +205,25 @@ aws: [ERROR]: An error occurred (NotImplemented) when calling the CreateChangeSe
 Simulated CloudFormation does not serve CreateChangeSet
 ```
 
-`create-stack` and `describe-stacks` do work. A deployment starts in the background and
-`create-stack` is answered before the Resources exist, as real CloudFormation answers it.
+Use `create-stack` and `describe-stacks` instead. `create-stack` returns while resource creation runs
+in the background.
 
-### Presigning needs the S3 service hostname
+### Presigned S3 URLs
 
-`aws s3 presign` signs whatever endpoint the CLI is configured with, and a URL built over the
-general endpoint has no Bucket in it for the endpoint to route on. Point the one command at
-simulated S3's own hostname on the served port:
+Run `aws s3 presign` against the configured endpoint:
 
 ```bash
-aws --endpoint-url http://s3.us-east-1.sim-aws.localhost:8787 s3 presign s3://widgets/one.txt
+aws s3 presign s3://widgets/one.txt
 ```
 
-The URL that comes back is fetchable by anything, including `curl` and a browser. The same hostname
-serves [presigned URLs built by the SDK](https://yulinsim.dev/services/s3/#presigned-urls).
+The returned URL includes a signed credential scope, which Yulin uses to route the request to S3.
+It works with `curl`, a browser, or another HTTP client. The S3 guide also covers
+[presigned URLs built with the SDK](https://yulinsim.dev/services/s3/#presigned-urls).
 
 ### A bad key looks like an XML parse failure
 
-STS, IAM and ELBv2 speak the AWS Query protocol and expect an XML body. The endpoint answers a
-rejected signature as JSON. The CLI reports the body it could not parse:
+STS, IAM, and ELBv2 return XML responses. Yulin currently returns a rejected signature as JSON for
+these services, so the CLI reports an XML parsing error:
 
 ```bash
 aws sts get-caller-identity
@@ -250,18 +233,38 @@ XML received. Further retries may succeed:
 b'{"Message":"Forbidden"}'
 ```
 
-`Forbidden` in the quoted body is the real answer. The other seventeen services report the same
-rejection as a plain `403`.
+The `{"Message":"Forbidden"}` body means that the access key or signature was rejected. Other served
+services report the rejection as a plain `403`.
+
+## Available functionality
+
+The served AWS API supports CLI operations for these services:
+
+- ACM
+- CloudFormation
+- CloudWatch metrics and CloudWatch Logs
+- Cognito Identity Provider
+- DynamoDB and DynamoDB Streams
+- ECS and Elastic Load Balancing v2
+- EventBridge
+- IAM and STS
+- KMS and Secrets Manager
+- Lambda
+- Rekognition
+- S3
+- SNS and SQS
+- SSM Parameter Store
+
+Profiles and role assumption work with the endpoint. Client-side features such as JMESPath queries
+and output formatting work with simulated responses.
 
 ## Limitations
 
-- Five services are refused with `501 Not Implemented`. Route 53 and CloudFront speak REST-XML, and
-  API Gateway v2, SES v2 and EventBridge Scheduler speak REST-JSON. Every one of them is reachable
-  in process through `SimAws` and through [SDK interception](https://yulinsim.dev/sdk/). Simulated ECR is
-  refused the same way and has no AWS API surface at all, since its images are registered in
-  process.
-- An operation a served service has not implemented is refused as `NotImplemented`. That is a
-  separate answer from the protocol refusal above. `aws iam list-users` reports
+- Services absent from the list above are not available through the general AWS API endpoint. Use
+  `SimAws` directly or [SDK interception](https://yulinsim.dev/sdk/) where the service supports it.
+  Simulated ECR exposes only an in-process API.
+- An unsupported operation on a served service returns `NotImplemented`. For example,
+  `aws iam list-users` reports
   `Simulated IAM does not serve ListUsers`, and `aws lambda list-functions` names the path it
   arrived at.
 - `aws cloudwatch get-metric-statistics` and `aws cloudwatch get-metric-data` fail with
@@ -269,16 +272,3 @@ rejection as a plain `403`.
   seconds and the endpoint hands that number to the simulation where a `Date` is expected. Both
   reads work in process and through SDK interception. `put-metric-data` and `list-metrics` are
   unaffected.
-- `aws s3 cp` and `aws s3 sync` corrupt a **download** above the CLI's 8MB threshold
-  ([#717](https://github.com/KensioSoftware/yulin/issues/717)). The CLI splits
-  the download into ranged GETs, simulated S3 ignores `Range` and returns the whole Object for each
-  one, and the parts land on top of each other. A 12MB Object arrives as a 20MB file. Uploads above
-  the threshold are fine, and so is any download under it. Two ways round it, both verified.
-  `aws s3api get-object` issues one unranged GET. Raising the threshold in the config file keeps
-  `aws s3 cp` on a single GET too.
-
-  ```ini
-  [profile sim]
-  s3 =
-    multipart_threshold = 5GB
-  ```

package/docs/factories/README.md

@@ -1,36 +1,11 @@
 # Event factories
 
-A handler is invoked with an event, and a test of a handler has to produce one. The events AWS
-delivers are large, most of each one is fields the handler never reads, and the two or three the
-test is about are buried in them. Written out by hand, that literal is copied between files and
-drifts.
+Yulin's event factories create complete AWS event objects for tests that call a handler directly.
+They use [`@kensio/part-factory`](https://partfactory.dev/) and do not need a `SimAws` instance.
 
-Yulin exports [`@kensio/part-factory`](https://partfactory.dev/) factories for those event shapes. A
-test made with one says what the request or the message was and leaves the rest of the event alone.
-They are ordinary factories, made in-process, and they need no `SimAws` instance and no simulated
-service running. A handler test that runs without a simulator is who they are for. A test that does want
-one (a Function URL served over HTTP, a queue with a real event source mapping) gets its events from
-the simulator, and these factories make the same shapes that simulator delivers.
+## Make a record or an event
 
-## What is exported
-
-| Factory                                                                       | Import                       | Event                               |
-| ----------------------------------------------------------------------------- | ---------------------------- | ----------------------------------- |
-| `lambdaFunctionUrlEventFactory`                                               | `@kensio/yulin/lambda`       | A Lambda Function URL invocation    |
-| `lambdaSqsEventFactory`, `lambdaSqsEventRecordFactory`                        | `@kensio/yulin/lambda`       | An SQS event source mapping's batch |
-| `lambdaDynamoDbStreamEventFactory`, `lambdaDynamoDbStreamEventRecordFactory`  | `@kensio/yulin/lambda`       | A DynamoDB stream mapping's batch   |
-| `httpApiProxyEventFactory`                                                    | `@kensio/yulin/apigatewayv2` | An HTTP API `AWS_PROXY` invocation  |
-| `s3NotificationEventFactory`, `s3NotificationEventRecordFactory`              | `@kensio/yulin/s3`           | An S3 event notification            |
-| `cloudFrontViewerRequestEventFactory`, `cloudFrontViewerResponseEventFactory` | `@kensio/yulin/cloudfront`   | A CloudFront Functions event        |
-
-Each service's own documentation covers what its events mean. This page is about how the factories
-are shaped and what they have in common.
-
-## One factory per shape, and one per record
-
-An event that carries a list of records has two factories, one for a record and one for the event
-around it. The record factory makes one record, and the event factory completes as many records as
-the test asks for.
+Pass the fields that matter to the test. The factory supplies the remaining fields:
 
 ```typescript factories-records-and-events
 /**
@@ -68,17 +43,14 @@ const event = lambdaSqsEventFactory.make({
 console.log(ordersHandler(event));
 ```
 
-The event factory exists so a test can pass partial records like that. A `DynamicFactory` whose
-defaults hold one record would not manage it. Overrides are merged onto defaults, and merging
-replaces a list whole rather than element by element. A partial record passed that way would reach
-the handler as the only thing in those records, typed as a complete one and missing every field the
-handler reads.
+Factories whose names end in `RecordFactory` create one record. Their matching event factories
+create the object that contains a `Records` array. The event factory makes one record by default and
+completes every partial record passed in `Records`.
 
-## Named variations
+## Reuse a named event shape
 
-Every factory here is an `ItemFactory`. A variation with a name is a `VariantFactory` around it, the
-same as for any other `part-factory` factory. That is usually the tidiest way to describe the kind
-of request or message one application receives:
+Every exported event factory implements `ItemFactory`. Wrap one in a `VariantFactory` to keep a
+common event shape in one place:
 
 ```typescript factories-variants
 /**
@@ -118,23 +90,39 @@ console.log(
 );
 ```
 
-## Events that agree with themselves
+## Keep related fields consistent
+
+AWS events often repeat the same value in several fields. The factories calculate those fields from
+the overrides. For example, an SQS record's `md5OfBody` follows its `body`, and an S3 notification's
+bucket ARN follows its bucket name.
 
-A real AWS event says the same thing in more than one field, and those copies are where a
-hand-written literal goes wrong. It asks for `/user/status` and leaves the request context saying
-`/`, or gives an SQS record the digest of some other body, or reports a DynamoDB insert on a record
-that carries an old image.
+The factories keep these groups consistent:
+
+- Function URL and HTTP API request paths, route keys, query strings, endpoint details, caller
+  details, and invocation times
+- SQS message bodies, body digests, queue ARNs, and regions
+- DynamoDB stream images, event names, view types, stream ARNs, and regions
+- S3 bucket names, bucket ARNs, event names, and object metadata
+
+You can still override both copies with different values. The factory preserves explicit overrides,
+even when AWS would not produce that combination.
+
+## Available factories
+
+| Factory                                                                       | Import                       | Event                               |
+| ----------------------------------------------------------------------------- | ---------------------------- | ----------------------------------- |
+| `lambdaFunctionUrlEventFactory`                                               | `@kensio/yulin/lambda`       | A Lambda Function URL invocation    |
+| `lambdaSqsEventFactory`, `lambdaSqsEventRecordFactory`                        | `@kensio/yulin/lambda`       | An SQS event source mapping's batch |
+| `lambdaDynamoDbStreamEventFactory`, `lambdaDynamoDbStreamEventRecordFactory`  | `@kensio/yulin/lambda`       | A DynamoDB stream mapping's batch   |
+| `httpApiProxyEventFactory`                                                    | `@kensio/yulin/apigatewayv2` | An HTTP API `AWS_PROXY` invocation  |
+| `s3NotificationEventFactory`, `s3NotificationEventRecordFactory`              | `@kensio/yulin/s3`           | An S3 event notification            |
+| `cloudFrontViewerRequestEventFactory`, `cloudFrontViewerResponseEventFactory` | `@kensio/yulin/cloudfront`   | A CloudFront Functions event        |
 
-Each factory's defaults are computed from the overrides, so supplying either copy settles the other.
-What that covers is listed in each factory's own documentation, and in outline it is:
+Each service page describes the fields and defaults for its own factories.
 
-- **Function URL and HTTP API events** — the path, the query, the route key, the endpoint's id,
-  hostname and `host` header, the caller's user agent and address, and the invocation time
-- **SQS records** — the digest of the body, and the Region of the queue ARN
-- **DynamoDB stream records** — the images the reported change would carry, the view type naming
-  the images that are there, and the Region of the stream ARN
-- **S3 notification records** — the ARN of the Bucket named, and whether the Object still exists to
-  have a size and an eTag
+## Limitations
 
-Overriding both copies of one of those with different values is still allowed. A test that wants an
-event no real invocation would produce is entitled to one. It just has to ask for it twice.
+- Event factories create data only. They do not invoke a Lambda function, apply IAM permissions, or
+  run another simulated service.
+- A factory accepts explicit overrides that disagree with each other. It does not validate that the
+  final event could have come from AWS.