@kensio/yulin 1.21.6 → 1.21.8

package/docs/services/kms/README.md

@@ -1,17 +1,15 @@
 # Simulated KMS
 
-Yulin includes a simulated AWS Key Management Service (KMS) for tests and local development.
-
-Encryption is real. Each simulated key holds AES-256 key material and the operations run through
-Node.js's own `crypto`. A ciphertext can only be read with its key, and a decryption with the wrong
-encryption context fails.
+Yulin simulates AWS Key Management Service (KMS) in memory. Symmetric keys use AES-256 key material,
+and asymmetric keys use real key pairs. Cryptographic operations run through Node.js `crypto`, so
+the wrong key or encryption context cannot decrypt a ciphertext.
 
 KMS-specific types are imported from the `@kensio/yulin/kms` subpath.
 
 ## Encrypting and decrypting
 
-Create a key and use it. `Decrypt` needs no `KeyId` for a symmetric key, because the ciphertext
-already names the key that produced it.
+Create a key, encrypt a value, then decrypt it. `Decrypt` does not need a `KeyId` for symmetric
+ciphertext because the ciphertext identifies its key.
 
 ```typescript sim-kms-encrypt-decrypt
 /**
@@ -52,8 +50,8 @@ any second `SimAws` instance both reject it.
 
 ## Encryption context
 
-An encryption context is non-secret key/value data bound to a ciphertext. Decryption with a
-different context fails. That ties a ciphertext to the thing it belongs to.
+An encryption context binds non-secret key/value data to a ciphertext. Decryption requires the same
+context.
 
 ```typescript sim-kms-encryption-context
 /**
@@ -100,9 +98,8 @@ The context is an unordered map. The same pairs written in a different order sti
 
 ## Envelope encryption
 
-`Encrypt` takes at most 4096 bytes. That limit is what makes envelope encryption necessary.
-`GenerateDataKey` returns a data key twice, once in the clear to encrypt your data with, and once
-encrypted under the KMS key to store alongside it.
+`Encrypt` accepts at most 4,096 bytes. For larger values, use `GenerateDataKey`. It returns a
+plaintext data key for encryption and an encrypted copy to store with the data.
 
 ```typescript sim-kms-generate-data-key
 /**
@@ -141,8 +138,8 @@ console.log(recovered.Plaintext?.length); // 32
 
 ## Signing and verifying
 
-A key created with `KeyUsage: SIGN_VERIFY` holds a real key pair, and the signatures are real
-signatures. A key spec is required, because the default `SYMMETRIC_DEFAULT` spec cannot sign.
+A key with `KeyUsage: SIGN_VERIFY` holds a real key pair. Set a signing key spec because the default
+`SYMMETRIC_DEFAULT` key cannot sign.
 
 ```typescript sim-kms-sign-verify
 /**
@@ -261,9 +258,8 @@ both matching what KMS produces. `GetPublicKey` against a symmetric key is
 
 ## Key policies and IAM
 
-Every KMS key has a policy, and it cannot be removed. An IAM policy granting `kms:Decrypt` only
-takes effect where the key's own policy admits the caller. How it admits them decides what else is
-needed:
+Every key has a key policy. An identity policy granting `kms:Decrypt` works only when the key policy
+also permits the caller:
 
 - A statement naming the caller grants access outright. A role with no permissions of its own can
   still use the key.
@@ -342,16 +338,15 @@ on real KMS.
 
 ## AWS managed keys and `kms:ViaService`
 
-An alias beginning `alias/aws/` names an AWS managed key, and the key is created the first time
-something references it. Such a key gets the policy real AWS gives it, which differs from the
-customer default:
+An alias beginning with `alias/aws/` names an AWS managed key. Yulin creates that key when it is
+first referenced and applies AWS-managed-key policy behavior:
 
 - Use of the key is allowed to any principal in the owning account, but only when `kms:ViaService`
   names the service that owns the key, such as `ssm.us-east-1.amazonaws.com` for `aws/ssm`.
-- The account root is allowed to read the key's metadata. That is the whole of what this policy
-  delegates to IAM.
+- The account root can read the key's metadata.
 
-That is why a role holding `kms:Decrypt` on such a key cannot use it by calling KMS itself.
+A role cannot use an AWS managed key by calling KMS directly, even when its identity policy grants
+`kms:Decrypt`.
 
 `kms:ViaService` is set by the service making the call on the caller's behalf. Sim SSM does this for
 `SecureString` parameters. Code calling simulated KMS directly sets it with the `viaService` request
@@ -417,8 +412,7 @@ and a condition on it stays unmatched.
 
 ## Naming a key
 
-Every operation takes its target as a `KeyId`, in any of the four forms real KMS accepts. Those are
-a key ID, a key ARN, an alias name such as `alias/app-key`, and an alias ARN.
+`KeyId` accepts a key ID, key ARN, alias name such as `alias/app-key`, or alias ARN.
 
 A key ARN or alias ARN naming another account or region resolves to no key at all. Its identifier is
 never read out and looked up locally. A foreign ARN cannot reach a key that happens to share an
@@ -473,8 +467,8 @@ console.log(managed.KeyMetadata?.KeyManager); // "AWS"
 
 A key can be disabled and re-enabled later. A disabled key stays present, and refuses to be used.
 
-Deletion is never immediate. `ScheduleKeyDeletion` sets a recovery window of 7 to 30 days, defaulting
-to 30. During that window the key refuses to be used but can still be recovered with
+`ScheduleKeyDeletion` sets a recovery window from 7 to 30 days, defaulting to 30. During that window
+the key cannot be used but can be recovered with
 `CancelKeyDeletion`. Cancelling leaves the key disabled. Re-enabling it is a separate step.
 
 A disabled key fails cryptographic operations with `DisabledException`. A key pending deletion fails
@@ -600,9 +594,7 @@ the function's execution role as the caller. A handler that decrypts a value the
 allowed to, by both the key policy and the role's identity policy, the same as on real AWS. See
 [simulated Lambda](https://yulinsim.dev/services/lambda/) for how function code and execution roles work.
 
-## Available functionality
-
-Sim KMS currently supports:
+## Supported operations
 
 - `CreateKeyCommand`, for symmetric encryption keys and asymmetric signing keys
 - `DescribeKeyCommand` and `ListKeysCommand`
@@ -619,8 +611,6 @@ Sim KMS currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - Only encryption with a symmetric key and signing with an asymmetric key are simulated. Left out
   are asymmetric encryption (`RSAES_OAEP_SHA_1` and `RSAES_OAEP_SHA_256`), HMAC keys and
   `GENERATE_VERIFY_MAC`, key agreement and `DeriveSharedSecret`, the `SM2` key spec, and

package/docs/services/lambda/README.md

@@ -1,7 +1,7 @@
 # Simulated Lambda
 
-Yulin includes a simulated AWS Lambda service for tests and local development. Functions are created
-and invoked in-process and in memory, with no containers and no real AWS infrastructure.
+Yulin creates and invokes Lambda functions in process. A function can use an in-process handler,
+code from a zip archive, code stored in simulated S3, or a handler bound to a container image.
 
 Handlers run with their execution role as the simulated caller, so AWS calls made inside a handler
 are authorized by simulated IAM, as on real Lambda. Creating a function and changing its role are
@@ -9,16 +9,14 @@ authorized as well, both against `lambda:` actions and against `iam:PassRole` on
 the request names. See [passing a Role to a service](https://yulinsim.dev/services/iam/#passing-a-role-to-a-service)
 in the IAM docs.
 
-Lambda-specific helpers are imported from the `@kensio/yulin/lambda` subpath. Real `LambdaClient`
-instances can be routed into sim Lambda with
+Lambda helpers are available from `@kensio/yulin/lambda`. A `LambdaClient` can be routed to Yulin with
 [SDK interception](https://yulinsim.dev/sdk/ "Simulated AWS SDK interception docs").
 
 ## Creating and invoking a function
 
-The quickest way to a working function is to pass a real in-process handler function through the
-SDK-shaped `Code.ZipFile` input with `makeLambdaZipFileInput(...)`. The handler is an ordinary
-function in your Node.js process. It can be stepped through in a debugger and can close over local
-state.
+Use `makeLambdaZipFileInput(...)` to pass an in-process handler through the SDK-shaped `Code.ZipFile`
+input. The handler runs as an ordinary function in the Node.js process. It supports breakpoints and
+access to local state.
 
 ```typescript sim-lambda-create-and-invoke
 /**
@@ -84,18 +82,13 @@ The invoke call itself returns normally.
 
 ## Zip-packaged code and the vm runtime
 
-A real in-process handler is the one to reach for first. `makeLambdaZipFileInput(...)` backs a
-function created through the SDK with one, and an [executable binding](#executable-bindings) backs
-one a template declares. The handler stops on a breakpoint and can close over the test's own state.
-Run the packaged code where the test is about the bundle a deployment ships, its imports and its
-bundling included. Both paths invoke through simulated Lambda, and simulated IAM authorizes the
-handler's own AWS calls under the execution role either way.
+Use an in-process handler for most tests. Use packaged code when the test covers the deployed bundle,
+including its imports. Both forms run through simulated Lambda and make AWS calls as the function's
+execution role.
 
-Real Lambda receives function code as a zip archive. `makeLambdaCodeZip(...)` builds real zip
-bytes from a source string (which becomes a single `index.js` module) or from a files map keyed by
-archive path (like a bundled deployment package). The archive runs in a Node.js `vm` context with
-real cold-start semantics. The module is imported once, on first invocation, and module state stays
-warm across invocations.
+`makeLambdaCodeZip(...)` builds zip bytes from a source string or a map of archive paths to file
+contents. A source string becomes `index.js`. Yulin runs the archive in a Node.js `vm`, loads the
+module on the first invocation and preserves module state for later invocations.
 
 ```typescript sim-lambda-zip-code-vm-runtime
 /**
@@ -171,18 +164,15 @@ package is refused at cold start. A handler file ending in `.mjs` is reported as
 Real Lambda has run ES module packages since nodejs14.x, and `NodejsFunction` in CDK emits one
 under `format: OutputFormat.ESM`.
 
-There are two ways round that. An [executable binding](#executable-bindings) or
-`makeLambdaZipFileInput(...)` backs the function with a real in-process handler. The test's own
-module system loads that handler, and its format is whatever the test file's is. An ESM project
-needs nothing further. Where the archive itself has to be the deployed artefact, compile a CommonJS
-build of the same source and deploy that as the function's code.
+Use an [executable binding](#executable-bindings) or `makeLambdaZipFileInput(...)` for an ESM handler.
+The test's module system loads an in-process handler. To test the archive itself, compile the source
+to CommonJS before creating the zip.
 
 `Code.ZipFile` bytes that fail to unzip are rejected at creation with the AWS-like
 `InvalidParameterValueException: Could not unzip uploaded file`.
 
-The archives are real zip files, and they interoperate with real tooling in both directions. A zip
-built by any other tool works as `Code.ZipFile` input, and `makeLambdaCodeZip` output can be
-unzipped normally.
+`Code.ZipFile` accepts zip archives produced by other tools. Archives from `makeLambdaCodeZip` can
+also be opened with standard zip tools.
 
 ### What a handler prints
 
@@ -408,9 +398,8 @@ writes none of those.
 
 ## Function code from S3
 
-Function code can also be fetched from a zip object stored in sim S3, as SAM and CDK deployments
-do on real AWS. The code object is fetched once at creation time, as the creating caller, so
-simulated IAM applies to the code object read.
+Function code may reference a zip object in simulated S3. Yulin reads the object once during
+function creation as the caller creating the function, so simulated IAM applies to the S3 read.
 
 ```typescript sim-lambda-s3-code
 /**
@@ -944,10 +933,9 @@ the operation header that says so.
 
 ## Invocation types
 
-`InvokeCommand` supports the three AWS invocation types. `RequestResponse` (the default) awaits
-the handler and returns its JSON-serialised result as the response payload. `Event` returns `202`
-immediately and runs the handler in the background. `DryRun` returns `204` without invoking the
-handler at all.
+`InvokeCommand` supports all three invocation types. `RequestResponse` waits for the handler and
+returns its JSON result. `Event` returns 202 and schedules the handler in the background. `DryRun`
+returns 204 without invoking the handler.
 
 ```typescript sim-lambda-invocation-types
 /**
@@ -1007,14 +995,12 @@ covers.
 
 ## Asynchronous retries and destinations
 
-An `Event` invocation whose handler throws is retried twice, as real Lambda retries one. The retries
-wait on the simulated clock, about a minute before the first and two before the second, so a test
-reaches them by advancing time rather than by waiting for it.
+An `Event` invocation retries a failed handler twice by default. Retries use the simulated clock,
+after about one minute and then two minutes. Advance the clock to run them in a test.
 
-`PutFunctionEventInvokeConfigCommand` changes how many retries a function makes and where its
-results go. An invocation that fails its last attempt is sent to the `OnFailure` destination, and
-one whose handler returns is sent to `OnSuccess`. A destination ARN can name a simulated SQS queue,
-SNS topic, EventBridge event bus or Lambda function.
+`PutFunctionEventInvokeConfigCommand` controls retry count and destinations. Lambda sends a final
+failure to `OnFailure` and a successful result to `OnSuccess`. Destinations may be SQS, SNS,
+EventBridge or another Lambda function.
 
 The source function's execution role must allow the operation that writes to the destination:
 
@@ -1154,11 +1140,9 @@ a config of its own, and an invocation of a qualifier with no config of its own
 
 ### Dead-letter targets
 
-`DeadLetterConfig` is the older way to keep a failed asynchronous invocation, and simulated Lambda
-takes it on `CreateFunction` and `UpdateFunctionConfiguration`. Its `TargetArn` names a simulated
-SQS queue or SNS topic, which receives the event as it was invoked rather than the destination
-record around it. The execution role needs `sqs:SendMessage` for a queue or `sns:Publish` for a
-topic. A denied delivery rejects the background task and leaves the target unchanged.
+`DeadLetterConfig` sends a failed asynchronous event to SQS or SNS. Configure it with
+`CreateFunction` or `UpdateFunctionConfiguration`. The target receives the original event rather
+than a destination record. The execution role needs `sqs:SendMessage` or `sns:Publish`.
 
 ```typescript sim-lambda-dead-letter-queue
 /**
@@ -1249,11 +1233,9 @@ A function carrying both a dead-letter target and an `OnFailure` destination sen
 
 ## Versions and aliases
 
-`PublishVersionCommand` copies a function as it stands and numbers the copy. The first is version
-`1`, and each later one counts up. The copy keeps the code, handler, timeout, memory and
-environment it was published with. `CreateAliasCommand` gives one of those versions a name, and
-`UpdateAliasCommand` moves the name to another version, so a deployment can repoint what callers
-invoke.
+`PublishVersionCommand` creates an immutable numbered copy of the function's code and configuration.
+Versions start at `1`. `CreateAliasCommand` gives a version a name, and `UpdateAliasCommand` moves
+that name to another version.
 
 `InvokeCommand` and `GetFunctionCommand` take a `Qualifier` naming a version number or an alias.
 The same qualifier can travel on the `FunctionName` instead, appended to the name (`orders:live`)
@@ -1366,9 +1348,8 @@ ARN. A `FunctionName` carrying a qualifier (`orders:live`) is refused with an
 
 ## Triggering a function from an SQS queue
 
-An event source mapping connects a [simulated queue](https://yulinsim.dev/services/sqs/ "Simulated SQS docs") to a function.
-Messages sent to the queue are delivered to the handler as an SQS event, with the `Records` shape
-real Lambda uses.
+An event source mapping polls a [simulated queue](https://yulinsim.dev/services/sqs/ "Simulated SQS docs") and invokes the function
+with an SQS `Records` event.
 
 Polling runs on the simulation's background scheduler. A test awaits
 `simAws.backgroundTasksComplete()` and then asserts, without sleeping.
@@ -1600,10 +1581,9 @@ from.
 
 ### When the handler fails
 
-A handler that returns normally has handled the batch, and the messages are deleted from the queue.
-A handler that throws returns the whole batch. The messages stay on the queue, hidden until their
-visibility timeout lapses, and are delivered again after that. Advancing the simulation's clock is
-what brings them back:
+A successful handler deletes the batch from the queue. When the handler throws, every message stays
+in flight until its visibility timeout expires, then becomes available for another delivery. Advance
+the simulated clock to reach that retry:
 
 ```typescript
 await simAws.clock().advanceBy({ seconds: 31 });
@@ -1618,10 +1598,8 @@ the sender sees is the message coming back.
 
 ### Reporting individual message failures
 
-A queue mapping created with `FunctionResponseTypes: ["ReportBatchItemFailures"]` takes the
-`batchItemFailures` list the handler returns. The message ids named in it go back to the queue, and
-the rest of the batch is deleted. A stream mapping takes the same list and does something else with
-it, under [reporting individual record failures](#reporting-individual-record-failures).
+A queue mapping with `FunctionResponseTypes: ["ReportBatchItemFailures"]` reads the handler's
+`batchItemFailures`. Named message IDs return to the queue and the remaining messages are deleted.
 
 ```typescript
 await simAws.lambda().createEventSourceMapping(
@@ -1646,9 +1624,8 @@ or an empty `batchItemFailures` list, has handled the whole batch.
 
 ### Making an SQS event without a queue
 
-A test of the handler on its own, with no queue and no mapping, still has to pass it a whole event.
-`lambdaSqsEventFactory` makes one, and `lambdaSqsEventRecordFactory` makes the records in it. Such a
-test then says what the messages carry and leaves the rest to the factory:
+Use `lambdaSqsEventFactory` and `lambdaSqsEventRecordFactory` to call an SQS handler without creating
+a queue or event source mapping:
 
 ```typescript sim-lambda-sqs-event-factory
 /**
@@ -1702,11 +1679,15 @@ Reporting individual failures can be tested against a made event too. The handle
 a template naming one is refused. The same Resource deploys a
 [stream mapping](#stream-mappings-in-templates), which has to have one.
 
+`Tags` is the one property recorded rather than refused. A template's tags are usually the whole
+stack's (a CDK app calling `Tags.of(app).add(...)` tags every mapping in it), and a mapping delivers
+the same records whether it carries them or not. The deploy stands and nothing reads them back.
+
 ## Triggering a function from a DynamoDB stream
 
-An event source mapping also connects a [simulated table's stream](https://yulinsim.dev/services/dynamodb/#capturing-changes-with-a-stream "Simulated DynamoDB streams docs")
-to a function. Changes to the table are delivered to the handler as a DynamoDB stream event, with
-the `Records` shape real Lambda uses.
+An event source mapping can also poll a
+[simulated DynamoDB stream](https://yulinsim.dev/services/dynamodb/#capturing-changes-with-a-stream "Simulated DynamoDB streams docs").
+Table changes reach the handler as a DynamoDB `Records` event.
 
 `StartingPosition` is required for a stream and is `TRIM_HORIZON` or `LATEST`. `TRIM_HORIZON` reads
 what the stream still holds, so changes made before the mapping existed are delivered too. `LATEST`
@@ -2054,9 +2035,8 @@ because a message the handler never takes is left to the queue's own redrive pol
 
 ### Reporting individual record failures
 
-A stream mapping created with `FunctionResponseTypes: ["ReportBatchItemFailures"]` takes the
-`batchItemFailures` list the handler returns. For a stream the identifier is the record's
-`SequenceNumber`:
+A stream mapping with `FunctionResponseTypes: ["ReportBatchItemFailures"]` reads the handler's
+`batchItemFailures`. Each item identifies a record by `SequenceNumber`:
 
 ```typescript
 await simAws.lambda().createEventSourceMapping(
@@ -2304,15 +2284,13 @@ Write the grant as an inline policy, as the example above and CDK both do.
 
 ## Triggering a function from a Kinesis stream
 
-An event source mapping also connects a [simulated Kinesis stream](https://yulinsim.dev/services/kinesis/ "Simulated Kinesis Data Streams docs")
-to a function. Records put onto the stream are delivered to the handler as a Kinesis event, with the
-`Records` shape real Lambda uses.
+An event source mapping can poll a
+[simulated Kinesis stream](https://yulinsim.dev/services/kinesis/ "Simulated Kinesis Data Streams docs") and invoke the function
+with a Kinesis `Records` event.
 
-A Kinesis stream has as many shards as it was created with, and every one of them is read. Real
-Lambda runs a processor per shard, and so does this: each shard keeps its own place on the stream,
-delivers its own batches and backs off on its own when a batch fails. One invocation is given
-records from one shard, so a handler that has to see records in order should put them under one
-partition key, which is what puts them on one shard.
+Yulin reads every shard in a Kinesis stream. Each shard tracks its own iterator, delivers its own
+batches and backs off independently after a failure. An invocation receives records from one shard.
+Use one partition key when the handler requires ordered records.
 
 `StartingPosition` is required for a stream. A Kinesis stream takes all three positions.
 `TRIM_HORIZON` reads what the stream still holds, `LATEST` reads only what arrives from the moment
@@ -4268,7 +4246,9 @@ Current documented limitations:
 - SQS queues, DynamoDB streams and Kinesis streams are the only event sources. Kafka, DocumentDB and
   Kinesis enhanced fan-out consumers are refused outright, and so are `FilterCriteria`,
   `ScalingConfig`, `DestinationConfig`, `BisectBatchOnFunctionError`, `ParallelizationFactor`,
-  `TumblingWindowInSeconds` and the other mapping inputs this simulation has no behaviour for.
+  `TumblingWindowInSeconds` and the other mapping inputs this simulation has no behaviour for. An
+  `AWS::Lambda::EventSourceMapping` carrying `Tags` is the exception, and deploys with the tags
+  dropped and the property recorded.
 - A failed stream batch waits 1, 2, 4, 8 and 16 seconds between attempts, where AWS documents no
   delay. That is deliberate. A delay of zero falls due at the instant the clock already reads, and a
   handler that always throws would leave `advanceBy` with work falling due forever. A mapping that

package/docs/services/logs/README.md

@@ -1,20 +1,15 @@
 # Simulated CloudWatch Logs
 
-Yulin includes a simulated Amazon CloudWatch Logs for tests and local development. It holds log
-groups, the streams inside them and the events written to those streams. A test can put log events
-and read them back with `GetLogEvents`, or search them with `FilterLogEvents`, without an AWS
-account.
-
-The point of it is to make log data addressable. Code that writes to CloudWatch Logs is code teams
-already have, and the alternative for a test is capturing process output.
+Yulin simulates CloudWatch Logs in memory. It stores log groups, streams, and events. Application
+code can write events through the normal SDK commands, and tests can read one stream with
+`GetLogEvents` or search a group with `FilterLogEvents`.
 
 CloudWatch Logs specific types are imported from the `@kensio/yulin/logs` subpath.
 
 ## Writing and searching log events
 
-A log group holds streams, a stream holds events, and `FilterLogEvents` searches across every
-stream in a group. A test can therefore name the group and leave the stream out, without knowing
-which execution environment wrote the line.
+`FilterLogEvents` searches every stream in a group. A test can find an event without knowing which
+execution environment wrote it.
 
 ```typescript sim-logs-write-and-search
 /**
@@ -86,11 +81,9 @@ set of alternatives, and a quoted phrase matches with its spaces intact.
 
 An omitted or empty pattern matches everything.
 
-The structured pattern syntaxes are refused. A JSON property pattern (`{ $.level = "ERROR" }`), a
+Yulin refuses structured pattern syntaxes. A JSON property pattern (`{ $.level = "ERROR" }`), a
 space delimited field pattern (`[level=ERROR, message]`) and a regular expression term
-(`%ERROR|WARN%`) each raise `SimLogsUnsupportedOperationException`. Approximating one would be
-worse. A pattern quietly treated as matching everything would turn an assertion about one log line
-into an assertion about any log line at all, and the test would keep passing while testing nothing.
+(`%ERROR|WARN%`) each raise `SimLogsUnsupportedOperationException`.
 
 ## Reading one stream
 
@@ -166,10 +159,8 @@ console.log(read);
 
 ## Retention
 
-Retention is held as a property to assert on. Events stay where they are, and seeing one go would
-mean moving the clock by months. What teams get wrong about retention is the value they deployed,
-ahead of the deletion that eventually follows from it. A log group with no retention keeps its
-events forever, the AWS default.
+Retention is stored and reported but leaves events in place. A log group without a retention setting
+keeps events forever, matching the AWS default.
 
 The accepted values are a fixed set. A reasonable-looking `retentionInDays: 10` is refused here
 exactly as it is by an account.
@@ -210,9 +201,8 @@ console.log(
 
 ## Lambda handler output
 
-A Lambda function's output is recorded into `/aws/lambda/<function name>` as it runs, whether its
-code is a zip archive or a real in-process handler. A test can then assert on what a handler logged
-by searching its log group.
+A simulated Lambda function writes its output to `/aws/lambda/<function name>`, whether it runs from
+a zip archive or an in-process handler. Search that group to assert on handler output.
 
 ```typescript sim-logs-lambda-output
 /**
@@ -256,11 +246,9 @@ const found = await simAws.logs().filterLogEvents(
 console.log(found.events?.[0]?.message);
 ```
 
-The output still reaches the terminal as well. Real Lambda sends it to CloudWatch Logs and nowhere
-else, but a test tool that swallowed it would make a failing test harder to debug. Recording is a
-tee.
+Output also remains visible in the terminal to help diagnose failing tests.
 
-An invocation that ends in an error nothing caught leaves an `ERROR Invoke Error` line in the group
+An invocation that ends in an uncaught error leaves an `ERROR Invoke Error` line in the group
 after whatever it printed, carrying the error's type, its message and its stack. The
 [simulated Lambda docs](https://yulinsim.dev/services/lambda/ "Simulated Lambda usage docs") show
 one.
@@ -272,8 +260,8 @@ shape in a test, and leave the value alone.
 
 Writing on this path is unconditional. A real function needs `logs:CreateLogGroup` and
 `logs:PutLogEvents` on its execution Role, and one without them produces no logs at all, in silence.
-Simulating that would leave nearly every function in a test logging nothing, with no failure to
-explain why.
+Yulin always captures this output so missing log permissions do not hide diagnostic messages in
+tests.
 
 ## Declaring a log group in a template
 
@@ -308,12 +296,11 @@ Two divergences to know about:
 
 ## Delivering logs from another service
 
-CloudWatch Logs delivery carries the logs of another service somewhere. CloudFront standard logging
-v2 is the clearest case. A distribution has no logging property of its own, and turning logging on
-means three CloudWatch Logs resources.
+CloudWatch Logs delivery connects a service's log source to a destination. CloudFront standard
+logging v2 uses a delivery source, a delivery destination, and a delivery.
 
-A delivery source names what is being logged and which of its logs. A delivery destination names
-where they land and in what form. A delivery joins one to the other.
+The source identifies the resource and log type. The destination identifies where logs would go and
+their output format. The delivery joins them.
 
 ```typescript sim-logs-delivery
 /**
@@ -418,7 +405,7 @@ rules from real AWS are modelled here, each of them a deploy that looks fine unt
 - **A delivery holds both its ends.** Deleting the source or the destination while a delivery joins
   them fails with `ConflictException`. The delivery goes first, and CloudFormation orders that
   itself when a stack is deleted.
-- **CloudFront delivers `ACCESS_LOGS` and nothing else.** Any other `logType` over a distribution is
+- **CloudFront supports only `ACCESS_LOGS`.** Any other `logType` over a distribution is
   refused.
 - **CloudFront delivery is set up from `us-east-1`**, whatever region the destination bucket is in.
   A CloudFront delivery source put from anywhere else is refused.
@@ -441,10 +428,9 @@ bare variables and let delivery name them.
 
 ### Declaring delivery in a template
 
-The same three resources in a template, which is the whole of what a CDK construct for CloudFront
-logging synthesises, alongside the distribution they are for. The source's `ResourceArn` is built
-around a `Ref` to that distribution, the way CDK builds it. A pinned distribution id fails the
-deploy (see [the rules above](#delivering-logs-from-another-service)).
+A CloudFormation template can declare the same three resources alongside the CloudFront distribution.
+The source's `ResourceArn` can use `Ref` to include the generated distribution ID. A hard-coded ID
+for a missing distribution fails deployment (see [the rules above](#delivering-logs-from-another-service)).
 
 ```yaml
 SiteDistribution:
@@ -501,9 +487,9 @@ The template carries the S3 layout as two flat properties, and the API takes the
 delivery. CloudWatch Logs issues that ID. A template cannot predict it.
 
 `Fn::GetAtt` gives `Arn` on all three. The source also publishes `Service` and `ResourceArns`, and
-the delivery publishes `DeliveryId` and `DeliveryDestinationType`. The destination publishes nothing
-else, and `DeliveryDestinationType` is a property of it rather than an attribute, so read that one
-off the delivery. Anything outside this set is refused here, as CloudFormation refuses it.
+the delivery publishes `DeliveryId` and `DeliveryDestinationType`. The destination publishes only
+`Arn`. Read `DeliveryDestinationType` from the delivery rather than the destination. CloudFormation
+refuses attributes outside this set.
 
 `Tags` and `DeliveryDestinationPolicy` are recorded as ignored properties, and the stack still
 deploys.
@@ -732,7 +718,8 @@ function is. `UpdateAlias` moves what the filter reaches, and the filter stays a
 
 ## Metric filters
 
-A metric filter turns matching log events into CloudWatch metric datapoints. It is how a log line becomes something an alarm can watch, with no handler publishing a metric of its own.
+A metric filter converts matching log events into CloudWatch metric datapoints. An alarm can then
+watch the metric without application code calling `PutMetricData`.
 
 ```typescript sim-logs-metric-filter
 /**
@@ -916,7 +903,9 @@ console.log(MetricAlarms?.[0]?.StateValue);
 
 ## Embedded Metric Format
 
-A log event that is itself an Embedded Metric Format document publishes the metrics it declares. This is how AWS Lambda Powertools counts anything. Its `Metrics` writes an EMF document to the handler's stdout and calls no CloudWatch API at all, and a CDK `NodejsFunction` bundling Powertools does the same in a deployed account.
+A log event containing an Embedded Metric Format (EMF) document publishes its declared metrics.
+AWS Lambda Powertools uses this path. It writes EMF to standard output instead of calling the
+CloudWatch API.
 
 ```typescript sim-logs-embedded-metric-format
 /**
@@ -997,7 +986,9 @@ A log event is read as a document only where it parses as JSON, comes out as an
 
 Three things go on `simAws.logs().metricPublicationFailures` rather than passing quietly. A metric the metadata declares and the document body carries no number under, a metric asking for `StorageResolution: 1`, which simulated CloudWatch has no period short enough for, and a directive that asked for dimensions and got no usable set of them.
 
-A dimension set is taken whole or dropped whole. One naming a key the body lacks, and one carrying anything but strings, are both dropped, because publishing part of a set would put the datapoint under a narrower identity than the document declared. A directive left with no usable set publishes nothing at all. Falling back to no dimensions would land the datapoint on the undimensioned metric, and that is one an alarm may well be watching.
+A dimension set is accepted or dropped as a whole. Yulin drops a set when the body lacks one of its
+keys or a value has a type other than string. Publishing only part of the set would create the wrong
+metric identity. A directive without a usable set produces no datapoint.
 
 Each entry on the ledger names its `source`, which is `{ kind: "metricFilter", filterName }` or `{ kind: "embeddedMetricFormat" }`. The two are told apart by kind rather than by name, because a metric filter may be called anything.
 
@@ -1132,7 +1123,7 @@ console.log(described.logGroups?.[0]?.logGroupArn);
 - **Events never expire.** Retention is stored and reported, never acted on.
 - **A metric filter reading a field of the log event.** A `metricValue` or a dimension value
   beginning `$` is refused where the filter is put. Both need a structured filter pattern, and
-  neither structured syntax is simulated.
+  both require a structured syntax, which Yulin refuses.
 - **How far back a `defaultValue` looks.** A filter remembers the most recent minute it matched
   something in. A later write into that same minute publishes no default over the top, and a write
   landing in an earlier minute a match was already seen in does publish one. Events
@@ -1143,21 +1134,21 @@ console.log(described.logGroups?.[0]?.logGroupArn);
   read, which is how it reaches CloudWatch in an account.
 - **`AWS::Logs::SubscriptionFilter`.** Recorded as a gap. The log group, the metric filter and the
   three delivery resource types are what simulated CloudFormation deploys here.
-- **`ApplyOnTransformedLogs` and `EmitSystemFieldDimensions` on a metric filter.** Recorded and
-  acted on by nothing. Log transformers are absent, so there is no transformed event to read.
-- **Nothing is actually delivered.** A delivery records that a source was joined to a destination
+- **`ApplyOnTransformedLogs` and `EmitSystemFieldDimensions` on a metric filter.** Recorded as
+  ignored properties. Log transformers are absent.
+- **Delivery resources store configuration only.** A delivery records that a source was joined to a destination
   and how the records would be written. No access log file ever reaches the bucket.
 - **`GetDeliverySource`, `GetDeliveryDestination` and `GetDelivery`.** Absent as SDK operations. The
   three `Describe` operations report the same resources. The three action names are authorized where
   CloudFormation reads a delivery Resource back.
 - **Delivery resource tags and cross-account delivery.** `PutDeliverySource`,
   `PutDeliveryDestination` and `CreateDelivery` refuse tags outright. `DeliveryDestinationPolicy` in
-  a template is recorded and acted on by nothing.
+  a template is recorded as an ignored property.
 - **An `=` in a suffix path with Hive compatible paths off.** Taken. Whether real CloudWatch Logs
   takes one is unverified. A path hand-rolling its own partition keys without the option is left
   alone here, and refused with the option on.
-- **Log types for services other than CloudFront.** Any `logType` is taken over a resource that is
-  not a distribution, because the valid set varies by service and this simulation does not carry it.
+- **Log types for services other than CloudFront.** Yulin accepts any `logType` for resources other
+  than distributions because the valid set varies by service.
 - **Logs Insights, export tasks, tags, encryption and data protection policies.** Absent. Tags and
   `kmsKeyId` on `CreateLogGroup` are refused outright. A property cannot look set here and behave
   differently in an account.