@kensio/yulin 1.20.15 → 1.20.16

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

@@ -3,12 +3,19 @@ import type { SimIamAccountResolver } from "../iam/registry/sim-iam-account-reso
 import type { SimAssumeRoleCommand, SimAssumeRoleCommandOutput } from "./command/assume-role/assume-role.command.js";
 import type { SimGetCallerIdentityCommand, SimGetCallerIdentityCommandOutput } from "./command/get-caller-identity/get-caller-identity.command.js";
 import type { SimAwsAccountRegionScope } from "../aws/sim-aws-account-region-scope.js";
-import type { SimAwsCaller } from "../aws/caller/sim-aws-caller.js";
+import type { SimAwsCaller, SimAwsDefaultCaller } from "../aws/caller/sim-aws-caller.js";
 import type { SimSdkCommandRouter } from "../../sdk/index.js";
 interface SimStsProperties {
     readonly accountRegionScope?: SimAwsAccountRegionScope;
     readonly iamResolver?: SimIamAccountResolver;
     readonly background?: BackgroundScheduler;
+    /**
+     * The caller this simulation attributes a request naming none to.
+     *
+     * Left out, such a request is the source Account's root principal, which is
+     * the identity GetCallerIdentity then reports.
+     */
+    readonly defaultCaller?: SimAwsDefaultCaller | undefined;
 }
 /**
  * Simulated AWS Security Token Service.
@@ -21,6 +28,7 @@ export declare class SimSts {
     private readonly accountRegionScope;
     private readonly background;
     private readonly iamResolver;
+    private readonly defaultCaller?;
     private readonly sdkRouter;
     constructor(properties?: SimStsProperties);
     /**

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

@@ -15,12 +15,14 @@ export class SimSts {
     accountRegionScope;
     background;
     iamResolver;
+    defaultCaller;
     sdkRouter = new SimStsSdkCommandRouter(this);
     constructor(properties = {}) {
         this.accountRegionScope =
             properties.accountRegionScope ?? simAwsAccountRegionScopeFactory.make();
         this.iamResolver = properties.iamResolver ?? new SimIamRegistry();
         this.background = properties.background ?? new BackgroundTasks();
+        this.defaultCaller = properties.defaultCaller;
     }
     /**
      * Handle an AssumeRoleCommand from the SDK.
@@ -31,6 +33,7 @@ export class SimSts {
             regionName: this.accountRegionScope.regionName,
             iamResolver: this.iamResolver,
             background: this.background,
+            defaultCaller: this.defaultCaller,
         });
         return await handler.handle(command, options);
     }
@@ -41,6 +44,7 @@ export class SimSts {
         const handler = new GetCallerIdentityCommandHandler({
             sourceAccountId: this.accountRegionScope.accountId,
             iamResolver: this.iamResolver,
+            defaultCaller: this.defaultCaller,
         });
         return await handler.handle(command, options);
     }

package/docs/README.md

@@ -0,0 +1,54 @@
+# Simulated AWS usage 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.
+
+## Service documentation
+
+- [ACM](https://yulinsim.dev/services/acm/ "Simulated ACM usage docs")
+- [API Gateway HTTP APIs](https://yulinsim.dev/services/apigatewayv2/ "Simulated API Gateway HTTP API usage docs")
+- [API Gateway REST APIs](https://yulinsim.dev/services/apigateway/ "Simulated API Gateway REST API usage docs")
+- [Athena](https://yulinsim.dev/services/athena/ "Simulated Amazon Athena usage docs")
+- [Bedrock](https://yulinsim.dev/services/bedrock/ "Simulated Amazon Bedrock usage docs")
+- [CloudFormation](https://yulinsim.dev/services/cloudformation/ "Simulated CloudFormation usage docs")
+- [CloudFront](https://yulinsim.dev/services/cloudfront/ "Simulated CloudFront usage docs")
+- [CloudWatch metrics](https://yulinsim.dev/services/cloudwatch/ "Simulated CloudWatch metrics usage docs")
+- [Cognito user pools](https://yulinsim.dev/services/cognito/ "Simulated Cognito user pools usage docs")
+- [DynamoDB](https://yulinsim.dev/services/dynamodb/ "Simulated DynamoDB usage docs")
+- [ECR](https://yulinsim.dev/services/ecr/ "Simulated ECR usage docs")
+- [ECS](https://yulinsim.dev/services/ecs/ "Simulated ECS usage docs")
+- [Elastic Load Balancing](https://yulinsim.dev/services/elbv2/ "Simulated Application Load Balancer usage docs")
+- [EventBridge](https://yulinsim.dev/services/eventbridge/ "Simulated EventBridge usage docs")
+- [Glue](https://yulinsim.dev/services/glue/ "Simulated Glue Data Catalog usage docs")
+- [IAM](https://yulinsim.dev/services/iam/ "Simulated IAM usage docs")
+- [Kinesis Data Firehose](https://yulinsim.dev/services/firehose/ "Simulated Kinesis Data Firehose usage docs")
+- [Kinesis Data Streams](https://yulinsim.dev/services/kinesis/ "Simulated Kinesis Data Streams usage docs")
+- [KMS](https://yulinsim.dev/services/kms/ "Simulated KMS usage docs")
+- [Lambda](https://yulinsim.dev/services/lambda/ "Simulated Lambda usage docs")
+- [CloudWatch Logs](https://yulinsim.dev/services/logs/ "Simulated CloudWatch Logs usage docs")
+- [Organizations](https://yulinsim.dev/services/organizations/ "Simulated Organizations service control policies usage docs")
+- [Personalize](https://yulinsim.dev/services/personalize/ "Simulated Amazon Personalize usage docs")
+- [Rekognition](https://yulinsim.dev/services/rekognition/ "Simulated Rekognition usage docs")
+- [Route53](https://yulinsim.dev/services/route53/ "Simulated Route53 usage docs")
+- [S3](https://yulinsim.dev/services/s3/ "Simulated S3 usage docs")
+- [Scheduler](https://yulinsim.dev/services/scheduler/ "Simulated EventBridge Scheduler usage docs")
+- [Secrets Manager](https://yulinsim.dev/services/secretsmanager/ "Simulated Secrets Manager usage docs")
+- [SES](https://yulinsim.dev/services/ses/ "Simulated SES usage docs")
+- [SNS](https://yulinsim.dev/services/sns/ "Simulated SNS usage docs")
+- [SQS](https://yulinsim.dev/services/sqs/ "Simulated SQS usage docs")
+- [SSM Parameter Store](https://yulinsim.dev/services/ssm/ "Simulated SSM Parameter Store usage docs")
+- [Step Functions](https://yulinsim.dev/services/stepfunctions/ "Simulated Step Functions usage docs")
+- [STS](https://yulinsim.dev/services/sts/ "Simulated STS usage docs")
+- [WAFv2](https://yulinsim.dev/services/wafv2/ "Simulated WAFv2 usage docs")
+
+## Feature documentation
+
+- [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")
+- [AWS SDK interception](https://yulinsim.dev/sdk/ "Simulated AWS SDK usage docs")
+- [Event factories](https://yulinsim.dev/factories/ "Test factories for AWS event shapes usage docs")
+- [Linting CloudFront Functions JS2](https://yulinsim.dev/lint/ "CloudFront Functions JS2 lint config usage docs")
+- [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")
+- [Terraform](https://yulinsim.dev/terraform/ "Deploying Terraform into simulated AWS usage docs")

package/docs/ai-skill/README.md

@@ -0,0 +1,69 @@
+# AI skill
+
+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.
+
+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
+
+```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.
+
+As a Claude Code plugin:
+
+```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.

package/docs/cli/README.md

@@ -0,0 +1,284 @@
+# AWS CLI
+
+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.
+
+[Serving on localhost](https://yulinsim.dev/serve/) is the reference for what each service serves. This page
+covers the way in from a shell.
+
+## 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:
+
+```typescript sim-cli-endpoint
+/**
+ * Serving a simulated environment for the aws CLI to reach.
+ */
+
+import {
+  CreateAccessKeyCommand,
+  CreateUserCommand,
+  PutUserPolicyCommand,
+} from "@aws-sdk/client-iam";
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const simIam = simAws.iam();
+
+await simIam.createUser(new CreateUserCommand({ UserName: "Operator" }));
+await simIam.putUserPolicy(
+  new PutUserPolicyCommand({
+    UserName: "Operator",
+    PolicyName: "Everything",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: { Effect: "Allow", Action: "*", Resource: "*" },
+    }),
+  }),
+);
+const created = await simIam.createAccessKey(
+  new CreateAccessKeyCommand({ UserName: "Operator" }),
+);
+
+const srv = await serveSimAws({ simAws, port: 8787 });
+
+// Paste these into the shell the CLI runs in.
+console.log(`export AWS_ENDPOINT_URL=http://localhost:${srv.port}`);
+console.log(`export AWS_ACCESS_KEY_ID=${created.AccessKey.AccessKeyId}`);
+console.log(
+  `export AWS_SECRET_ACCESS_KEY=${created.AccessKey.SecretAccessKey}`,
+);
+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.
+
+## Configuring the CLI
+
+Four environment variables are the whole configuration:
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:8787
+export AWS_ACCESS_KEY_ID=AKIAVEXOWARWMKBOA0MP
+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:
+
+```bash
+aws sts get-caller-identity
+{
+    "UserId": "AIDARNFLISEC7SCUNSDY",
+    "Account": "888888888888",
+    "Arn": "arn:aws:iam::888888888888:user/Operator"
+}
+```
+
+The credentials have to come from simulated IAM. Any other key is refused with `403 Forbidden`, and
+an unsigned request reaches nothing.
+
+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 named profile instead
+
+A profile in the CLI's own config file carries the same four values. The simulation then stays out
+of the ambient environment:
+
+```ini
+[profile sim]
+region = us-east-1
+endpoint_url = http://localhost:8787
+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.
+
+`role_arn` and `source_profile` work too. The CLI assumes the simulated Role for itself and signs
+with the session it gets back:
+
+```ini
+[profile reader]
+region = us-east-1
+endpoint_url = http://localhost:8787
+role_arn = arn:aws:iam::888888888888:role/Reader
+source_profile = sim
+```
+
+## Building the rest of the identities from the shell
+
+Only the first key has to come from the process that built the simulation. `aws iam` builds
+everything after it:
+
+```bash
+aws iam create-user --user-name shopper
+aws iam put-user-policy --user-name shopper --policy-name read-buckets \
+  --policy-document '{"Version":"2012-10-17","Statement":{"Effect":"Allow","Action":"s3:ListAllMyBuckets","Resource":"*"}}'
+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:
+
+```bash
+aws s3api create-bucket --bucket nope
+
+aws: [ERROR]: An error occurred (AccessDenied) when calling the CreateBucket operation: User:
+arn:aws:iam::888888888888:user/shopper is not authorized to perform: s3:CreateBucket on resource:
+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:
+
+```bash
+aws sts assume-role --role-arn arn:aws:iam::888888888888:role/Reader --role-session-name probe
+export AWS_ACCESS_KEY_ID=ASIAKBEUIHDMON9VBZXF
+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
+
+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.
+
+A quick tour of the ones a shell reaches for most:
+
+```bash
+aws s3 cp ./index.html s3://widgets/index.html
+aws s3 sync ./site s3://widgets/site/
+aws dynamodb put-item --table-name widgets --item '{"id":{"S":"w1"}}'
+aws sqs create-queue --queue-name orders
+aws ssm get-parameter --name /shop/url --query 'Parameter.Value' --output text
+aws secretsmanager get-secret-value --secret-id shop/db --query SecretString --output text
+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.
+
+[The serve docs](https://yulinsim.dev/serve/#which-services-answer) list the operations each service
+implements. Anything outside those lists is refused as `NotImplemented`.
+
+## 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.
+
+### `--payload` needs `--cli-binary-format`
+
+CLI v2 reads `--payload` as base64 by default:
+
+```bash
+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:
+
+```bash
+aws lambda invoke --function-name orders --payload '{"id":1}' \
+  --cli-binary-format raw-in-base64-out out.json
+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.
+
+### 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`.
+
+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`.
+
+### `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:
+
+```bash
+aws cloudformation deploy --stack-name site --template-file template.json
+
+aws: [ERROR]: An error occurred (NotImplemented) when calling the CreateChangeSet operation:
+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.
+
+### Presigning needs the S3 service hostname
+
+`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:
+
+```bash
+aws --endpoint-url http://s3.us-east-1.sim-aws.localhost:8787 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).
+
+### 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:
+
+```bash
+aws sts get-caller-identity
+
+aws: [ERROR]: Unable to parse response (not well-formed (invalid token): line 1, column 0), invalid
+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`.
+
+## 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
+  `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
+  `TypeError: time.getTime is not a function`. The JSON protocol carries a timestamp as epoch
+  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

@@ -0,0 +1,140 @@
+# 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 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.
+
+## 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.
+
+```typescript factories-records-and-events
+/**
+ * Making the SQS event a batch of messages arrives in.
+ */
+
+import {
+  lambdaSqsEventFactory,
+  lambdaSqsEventRecordFactory,
+  type SimLambdaSqsEvent,
+} from "@kensio/yulin/lambda";
+
+function ordersHandler(event: SimLambdaSqsEvent): readonly string[] {
+  return event.Records.map(
+    (record) => (JSON.parse(record.body) as { orderId: string }).orderId,
+  );
+}
+
+// One record, for a test about a single message.
+const record = lambdaSqsEventRecordFactory.make({
+  body: '{"orderId":"YL-1"}',
+});
+
+// [ 'YL-1' ]
+console.log(ordersHandler({ Records: [record] }));
+
+// A batch, saying only what each message carries. Everything else about each
+// record — its message id, its receipt handle, the digest of its body — is
+// filled in as a delivered record's is.
+const event = lambdaSqsEventFactory.make({
+  Records: [{ body: '{"orderId":"YL-1"}' }, { body: '{"orderId":"YL-2"}' }],
+});
+
+// [ 'YL-1', 'YL-2' ]
+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.
+
+## Named variations
+
+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:
+
+```typescript factories-variants
+/**
+ * Naming the variations of an event an application receives.
+ */
+
+import { VariantFactory } from "@kensio/part-factory";
+
+import { httpApiProxyEventFactory } from "@kensio/yulin/apigatewayv2";
+import { s3NotificationEventFactory } from "@kensio/yulin/s3";
+
+const signedInRequestFactory = new VariantFactory(httpApiProxyEventFactory, {
+  requestContext: {
+    authorizer: { jwt: { claims: { sub: "YL-1" }, scopes: null } },
+  },
+});
+
+const request = signedInRequestFactory.make({ rawPath: "/account" });
+
+// GET /account YL-1
+console.log(
+  request.routeKey,
+  request.requestContext.authorizer?.jwt?.claims["sub"],
+);
+
+const objectRemovedFactory = new VariantFactory(s3NotificationEventFactory, {
+  Records: [{ eventName: "ObjectRemoved:Delete" }],
+});
+
+const removal = objectRemovedFactory.make();
+
+// ObjectRemoved:Delete undefined
+console.log(
+  removal.Records[0]?.eventName,
+  // A removal reports no size, because the Object is gone.
+  removal.Records[0]?.s3.object.size,
+);
+```
+
+## Events that agree with themselves
+
+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.
+
+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:
+
+- **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
+
+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.