@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/personalize/README.md

@@ -1,17 +1,15 @@
 # Simulated Personalize
 
-Simulated Personalize holds the resources a recommendation is served from. No model is trained and
-no data is read, in the way simulated ACM issues certificates without producing real TLS
-certificates. A dataset group, a solution, a solution version and a campaign all exist, carry what
-the request gave them, and reach `ACTIVE` straight away.
+Yulin simulates the Personalize resources and API calls used to serve recommendations. It does not
+train a model or derive results from datasets. Tests declare the recommendations that a campaign or
+recommender should return. Created resources become `ACTIVE` immediately.
 
 Personalize-specific types are imported from the `@kensio/yulin/personalize` subpath.
 
 ## Building the chain to a campaign
 
-Every runtime recommendation names a campaign, and a campaign is the far end of a chain. The dataset
-group holds the data, the solution picks a recipe, the solution version is the trained model, and
-the campaign serves it.
+A campaign is built from a resource chain. A dataset group contains the datasets, a solution selects
+a recipe, a solution version represents the trained model, and a campaign serves that version.
 
 ```typescript sim-personalize-campaign-chain
 /**
@@ -73,9 +71,8 @@ expects.
 
 ## Recommendations from a campaign
 
-A campaign answers the runtime API from results declared against it. No model is fitted and no
-interaction history is held. A test says what one campaign recommends for one item, and the code
-under test makes the calls it would make against AWS.
+A campaign returns results declared during test setup. Application code still sends the same
+Personalize Runtime commands it sends to AWS.
 
 The two runtime operations live on `simAws.personalizeRuntime()`, and an intercepted
 `PersonalizeRuntimeClient` reaches the same place. They arrive from a separate SDK package
@@ -140,9 +137,8 @@ const recommended = await simAws.personalizeRuntime().getRecommendations(
 console.log(recommended.itemList?.map((item) => item.itemId).join(" "));
 ```
 
-Results are declared per campaign, through `recommendations()` and `rankings()`. A campaign serves
-one solution version trained on one recipe, and two campaigns in a dataset group answer the same
-entry differently.
+Declare results per campaign through `recommendations()` and `rankings()`. Two campaigns in the same
+dataset group can return different results for the same input.
 
 An item rule is read first where the request carries an item, then a user rule, then the default.
 That order follows the recipes. `aws-similar-items` requires an `itemId` and looks at no user, and
@@ -152,9 +148,8 @@ would have used. Matching is exact, with no pattern syntax.
 `numResults` cuts a declared list to length. A request no rule matches gets the campaign's default,
 and an empty `itemList` where no default is declared.
 
-An item is declared as an id on its own, or as an id with a score for a test to assert on. The
-number comes from the declaration, and a rule that leaves it out answers with an item carrying no
-score.
+Declare an item as an ID or as an ID with a score. An item declared without a score is returned
+without one.
 
 ```typescript sim-personalize-recommendation-scores
 /**
@@ -228,10 +223,8 @@ Runtime does.
 
 ## Datasets and schemas
 
-A dataset belongs to a dataset group and has one of five types. The dataset ARN carries the group
-and the type rather than the name the request gave, which is how real Personalize builds it. One
-dataset group therefore holds one dataset of each type, and two dataset groups can each hold an
-`INTERACTIONS` dataset without colliding.
+A dataset belongs to a dataset group and has one of five types. Its ARN contains the group and type,
+not the requested name. Each group can contain one dataset of each type.
 
 ```typescript sim-personalize-dataset
 /**
@@ -289,8 +282,8 @@ domain dataset group refuses them here too.
 
 ## Recording events
 
-An event tracker is where `PutEvents` sends item interactions. It is created against a dataset
-group and reports a tracking ID back, and every `PutEvents` names that ID.
+An event tracker records the item interactions sent through `PutEvents`. Create it for a dataset
+group, then pass its tracking ID to each request.
 
 ```typescript sim-personalize-event-tracker
 /**
@@ -464,10 +457,9 @@ console.log(group.domain);
 
 ## Recommenders and their use cases
 
-A recommender goes straight onto a Domain dataset group, for one of the ten use cases AWS trained.
-There is no solution and no solution version in between. `GetRecommendations` then names a
-`recommenderArn` where the custom path names a `campaignArn`, and results are declared against it
-through the same `recommendations()` rules.
+A recommender belongs directly to a domain dataset group and selects one of ten AWS use cases. It
+does not use a solution or solution version. Pass its ARN to `GetRecommendations` and declare its
+results with the same `recommendations()` API used for campaigns.
 
 ```typescript sim-personalize-recommender
 /**
@@ -525,9 +517,8 @@ Real Personalize trains for hours and retrains every seven days.
 
 ### The ten use cases
 
-The recipe ARN picks the use case, and the use case decides what a request has to carry. A request
-leaving out a parameter its use case requires is refused, which is what real Personalize does with
-it. That refusal is the part of the domain path worth simulating, and everything else here is state.
+The recipe ARN selects the use case. Each use case defines whether `itemId` and `userId` are
+required, optional, or unused. Requests missing a required parameter are rejected.
 
 | Use case                           | Recipe ARN suffix                              | `itemId` | `userId` |
 | ---------------------------------- | ---------------------------------------------- | -------- | -------- |
@@ -555,9 +546,6 @@ A parameter marked unused is ignored rather than matched on. A `Top picks for yo
 an `itemId` as well as its `userId` is answered from the user rule, since that is the tier real
 Personalize would have used. An optional one is matched where the request carries it.
 
-These are the requirements AWS documents against each use case. Both pages are worth reading before
-writing a request, since two of them differ from the e-commerce use case they otherwise mirror.
-
 ### Starting and stopping
 
 `StopRecommender` leaves the recommender in place and stops it serving. `GetRecommendations` against
@@ -602,8 +590,7 @@ and solutions gone. A group still holding one is reported as `ResourceInUseExcep
 
 `AWS::Personalize::DatasetGroup`, `AWS::Personalize::Schema`, `AWS::Personalize::Dataset`,
 `AWS::Personalize::Solution` and `AWS::Personalize::EventTracker` deploy into simulated Personalize.
-A project that declares them in CDK or CloudFormation can deploy the same template its application
-deploys, with no hand-written test setup.
+A project can deploy its synthesized template without hand-written Personalize setup.
 
 Each one goes through the ordinary create command. A template and an SDK caller get the same
 validation, the same refusals and the same ARN.
@@ -710,19 +697,16 @@ wiring one resource into another reads `Fn::GetAtt`. An event tracker publishes
 does not publish fails the deploy, since answering one would let a template deploy here and fail on
 AWS.
 
-### A stack stops at the solution
+### Resources without CloudFormation types
 
-CloudFormation has no `AWS::Personalize::Campaign` type and no `AWS::Personalize::Recommender` type.
-A campaign is what every runtime call names, and it is always created out of band through the SDK,
-the CLI or the console. A deployed stack gets as far as a solution and stops there. A test creates
-the solution version and the campaign itself, as the example above does. This is real Personalize
-behaviour and worth knowing before reading it as a gap in the simulation.
+CloudFormation has no `AWS::Personalize::Campaign` or `AWS::Personalize::Recommender` type. Create
+these resources through the SDK after deploying the stack, as the example above does.
 
 The domain path stops in the same place. `Domain` is a property of `AWS::Personalize::DatasetGroup`,
 and a template can declare a Domain dataset group. No `AWS::Personalize::Recommender` type exists to
 put a recommender on it.
 
-### Types a stack steps over
+### Skipped resource types
 
 `AWS::Personalize::BatchInferenceJob`, `AWS::Personalize::BatchSegmentJob`,
 `AWS::Personalize::DataDeletionJob`, `AWS::Personalize::MetricAttribution` and
@@ -763,9 +747,9 @@ console.log(group?.name, group?.status);
 
 ## Deleting resources
 
-Deletion follows real Personalize. A dataset group holding datasets, solutions or an event tracker
-is reported as `ResourceInUseException`, and so is a solution a campaign still deploys. Tear a chain
-down from the campaign end.
+Delete resources from the campaign end of the chain. A dataset group that still contains datasets,
+solutions, or an event tracker raises `ResourceInUseException`. A solution still used by a campaign
+raises the same error.
 
 Deleting an event tracker leaves the events it accepted recorded, as real Personalize leaves the
 interactions it wrote in the dataset behind it.

package/docs/services/rekognition/README.md

@@ -1,8 +1,8 @@
 # Simulated Rekognition
 
-Simulated Rekognition answers detection calls from results declared against images. A test can say
-which image fails moderation or holds a cat, with no image analysis happening. The bytes are never
-looked at.
+Yulin simulates Rekognition by returning results declared for an image name or content hash. It does
+not analyze the image. Tests can define labels, moderation results, faces, and face matches while
+application code uses the normal Rekognition commands.
 
 Rekognition-specific types are imported from the `@kensio/yulin/rekognition` subpath.
 
@@ -67,9 +67,8 @@ const detected = await simAws
 
 ## Detecting labels in an image
 
-`DetectLabels` answers with the objects, scenes and concepts an image is declared to hold. Each
-label carries the parents, aliases, categories and instances it was declared with, and no more. A
-label is reported as written.
+`DetectLabels` returns the objects, scenes, and concepts declared for an image. Each label contains
+only the parents, aliases, categories, and instances in its declaration.
 
 ```typescript sim-rekognition-detect-labels
 /**
@@ -131,19 +130,16 @@ console.log(detected.LabelModelVersion); // "3.0"
 Labels come back in descending order of confidence, which is the order real Rekognition reports them
 in. A declared instance with no confidence of its own takes its label's.
 
-An image no rule matches gets the built-in default result. That is the one `Mobile Phone` label from
-the example response in the AWS `DetectLabels` documentation, with the parent, alias, category and
-bounding box AWS documents it with. It is a real Rekognition response, though which labels an
-unconfigured image gets is a simulator convention rather than what AWS would return for it.
+An image that matches no rule gets a built-in `Mobile Phone` result based on the AWS
+`DetectLabels` example response. This default is a Yulin convention. AWS results depend on the image.
 
-A label name fills in nothing of its own. Declaring `Cat` with no parents reports `Cat` with no
-parents, and declaring a `Pizza` nobody has heard of reports `Pizza`. Yulin ships no general label
-ontology to check a name against or to expand one from.
+Yulin does not validate or expand general detection labels. Declaring `Cat` without parents returns
+`Cat` without parents.
 
 ## Detecting faces in an image
 
-`DetectFaces` answers with the faces an image is declared to hold. A face says where it is and what
-it looks like, and the response carries the attributes the request asked for.
+`DetectFaces` returns the faces declared for an image, including their positions and requested
+attributes.
 
 ```typescript sim-rekognition-detect-faces
 /**
@@ -204,8 +200,7 @@ Faces come back in the order they were declared. An attribute with no confidence
 the face's, and a face detected at 99.4 is reported as smiling at 99.4. A face declared with no
 confidence at all is detected at the built-in one.
 
-An image with nobody in it is `{ faces: [] }`. Two built-in results cover the counting a test
-usually does:
+Use `{ faces: [] }` for an image with no faces. Two built-in results cover common face-count tests:
 
 ```typescript
 import {
@@ -219,10 +214,8 @@ faces.onName("incoming/landscape.png", simRekognitionNoFaces);
 faces.onName("incoming/crowd.png", simRekognitionSeveralFaces);
 ```
 
-An image no rule matches gets the built-in default result. That is the one face from the example
-response in the AWS `DetectFaces` documentation, with the attributes and all thirty landmarks AWS
-documents it with. It is a real Rekognition response, though which face an unconfigured image gets is
-a simulator convention rather than what AWS would return for it.
+An image that matches no rule gets the face from the AWS `DetectFaces` example response, including
+its attributes and 30 landmarks. This default is a Yulin convention.
 
 ## Choosing the facial attributes
 
@@ -305,11 +298,10 @@ excludes the chin.
 
 ## Declaring results
 
-Results are declared per operation. `moderation()` holds the rules `DetectModerationLabels` answers
-from, `labels()` holds the rules `DetectLabels` answers from, `faces()` holds the rules
-`DetectFaces` answers from, and `faceMatches()` holds the rules `SearchFacesByImage` answers from.
-All four take the same three kinds of rule, being an exact S3 object name, an exact content hash, or
-anything at all.
+Declare results separately for each operation. Use `moderation()` for `DetectModerationLabels`,
+`labels()` for `DetectLabels`, `faces()` for `DetectFaces`, and `faceMatches()` for
+`SearchFacesByImage`. Each API accepts rules for an exact S3 object name, an exact content hash, or a
+default result.
 
 ```typescript sim-rekognition-moderation-rules
 /**
@@ -340,8 +332,8 @@ moderation.onHash(simRekognitionImageHash(fixture), {
 });
 ```
 
-A hash rule wins, then a name rule, then the default. Matching is exact, with no pattern syntax.
-Which rule applies never depends on how specific a pattern looks.
+Rules use exact matching. Hash rules take precedence over name rules, which take precedence over the
+default.
 
 A name is the `Name` in the request, the S3 object key. It is matched on its own, with the Bucket
 left out, so a rule for a key applies to that key in whichever Bucket the request names. An image
@@ -412,9 +404,8 @@ refused where the rule is written.
 
 ## Sample images
 
-Simulated Rekognition ships with five images whose hashes are already declared. A test uploads one
-through its own code and gets a known answer without registering anything. That is what makes an
-application generating its own object keys testable, since the test never has to know the key.
+Yulin includes five small images with predeclared hash rules. Application code can upload one under
+any object key and receive a known result without registering another rule.
 
 | Image                                              | Format | Detected as                                       |
 | -------------------------------------------------- | ------ | ------------------------------------------------- |
@@ -477,9 +468,8 @@ simAws
   .onHash(simRekognitionImageHash(sample), { labels: [] });
 ```
 
-The images are real 16 by 16 PNG and JPEG files, 1,909 bytes in total. The format check reads their
-magic bytes as it does for any other image. What they are pictures of decides nothing, since no
-image is looked at.
+The images are valid 16 by 16 PNG and JPEG files. Rekognition checks their file signatures but does
+not inspect their visual content.
 
 ## Moderation labels come back with their parents
 
@@ -772,7 +762,7 @@ ever. Filter the notification configuration by prefix or suffix, as this one doe
 
 ## Face collections
 
-A collection is what lets an application recognise the same person twice, where a detection answers what is in one image.
+A collection stores indexed faces so an application can search for the same person later.
 
 ```typescript sim-rekognition-collections
 /**
@@ -970,9 +960,7 @@ An image is read from a Bucket in another Account when that Bucket's policy allo
 real Rekognition reads across Accounts. A Bucket in another Region is refused, as real Rekognition
 reads only Buckets in its own Region.
 
-## Available functionality
-
-Simulated Rekognition currently supports:
+## Supported operations
 
 - `DetectModerationLabelsCommand`, `DetectLabelsCommand` and `DetectFacesCommand`, for an image
   supplied as `Image.Bytes` or as `Image.S3Object`

package/docs/services/route53/README.md

@@ -1,11 +1,12 @@
 # Simulated Route53
 
-Yulin includes a simulated Route53 service for tests and local development.
+Yulin simulates Amazon Route 53 hosted zones, records and DNSSEC configuration for tests and local
+development. You can manage them through the AWS SDK or deploy them from CloudFormation and CDK
+templates. When Yulin serves the simulation on localhost, Route 53 records can route local hostnames
+to simulated services such as CloudFront distributions and S3 bucket websites.
 
-Sim Route53 can be used directly through `SimAws`, instantiated on its own as `SimRoute53`, and used
-by sim CloudFormation when deploying Route53 resources from CloudFormation or CDK templates. When
-served on localhost, Route53 records can route custom local hostnames to other simulated AWS
-services, such as simulated CloudFront distributions or simulated S3 bucket websites.
+Use Route 53 through `SimAws` when it should share state with other services. Use `SimRoute53`
+directly when you need an isolated Route 53 simulation.
 
 ## Basic Hosted Zone usage
 
@@ -54,8 +55,8 @@ console.log(hostedZoneOut.HostedZone?.ResourceRecordSetCount);
 Hosted Zone names are normalised with a trailing dot in Route53-style outputs, so `example.test`
 becomes `example.test.`.
 
-Hosted Zone creation uses background tasks to move the zone to `INSYNC`. If your test needs final
-state, call `await simAws.backgroundTasksComplete()` before continuing.
+Hosted zone creation moves the zone to `INSYNC` in a background task. Call
+`await simAws.backgroundTasksComplete()` before asserting on the final state.
 
 Hosted Zone IDs are accepted in any real Route53 shape, being a `Z` prefix followed by uppercase
 alphanumerics, up to 32 characters. A real Hosted Zone ID copied out of an AWS account, such as
@@ -65,14 +66,12 @@ alphanumerics, up to 32 characters. A real Hosted Zone ID copied out of an AWS a
 
 ## Registering a Hosted Zone with a chosen ID
 
-`CreateHostedZoneCommand` allocates its own Hosted Zone ID, as real Route53 does, and takes none
-from you. When something else already decided the ID, register the Hosted Zone as part of your test
-setup instead.
+`CreateHostedZoneCommand` allocates the hosted zone ID. When a synthesized template already contains
+an ID, register that hosted zone during test setup instead.
 
-The usual reason is a CDK app that looks its zone up with `HostedZone.fromLookup` instead of
-creating it. That bakes the real Hosted Zone ID into the synthesized template, and every
-`AWS::Route53::RecordSet` in the template names that ID. Registering the zone first lets the
-template deploy as it is, with no rewriting.
+For example, `HostedZone.fromLookup` writes the resolved hosted zone ID into the synthesized
+template. Registering that ID before deployment lets its `AWS::Route53::RecordSet` resources deploy
+without changing the template.
 
 ```typescript sim-route53-register-hosted-zone
 /**
@@ -1701,8 +1700,9 @@ await scopedRoute53.createHostedZone(
 );
 ```
 
-Each `SimAws` instance has its own isolated state. Create a fresh instance per test, or share one
-across related local setup.
+Each `SimAws` instance has its own isolated state. Application tests should normally use the instance
+from their shared [test suite setup](https://yulinsim.dev/testing/). A fresh instance remains useful
+when a test specifically needs an empty simulated account.
 
 ## Standalone SimRoute53
 
@@ -1732,7 +1732,7 @@ console.log(hostedZoneCreation.HostedZone?.Id);
 A standalone `SimRoute53` instance has its own isolated state, standing apart from any wider
 `SimAws` environment. Use `SimAws` when Route53 needs to resolve names to other simulated services.
 
-## Available functionality
+## Supported operations
 
 Sim Route53 currently supports:
 

package/docs/services/s3/README.md

@@ -1,13 +1,12 @@
 # Simulated S3
 
-Yulin includes a simulated S3 service for tests and local development.
+Yulin simulates S3 buckets, objects, policies, notifications and website hosting. Use
+`simAws.s3()` as part of a simulated AWS environment or create a standalone `SimS3`.
+`serveSimAws` exposes the S3 API and website endpoints over localhost.
 
-Sim S3 can be used directly through `SimAws` or instantiated on its own as `SimS3` with isolated
-state. Yulin can serve a simulated S3 service on localhost.
+## Create a bucket and object
 
-## Basic usage
-
-Create a simulated AWS environment, get simulated S3, create a Bucket, and put an Object into it.
+Create a bucket, write an object and read it back.
 
 ```typescript sim-s3-bucket
 /**
@@ -104,15 +103,15 @@ await scopedS3.createBucket(
 );
 ```
 
-Within one `SimAws` instance, Bucket names are globally registered across Accounts and Regions.
-Creating a Bucket with a name already used in another simulated Region or Account throws an error.
+Bucket names are global within a `SimAws` instance. Creating the same name in another simulated
+account or region fails.
 
-Each `SimAws` instance has its own isolated state. Create a fresh one per test or share one across
-all tests, as you prefer.
+Each `SimAws` instance has isolated state.
 
-## Listing Buckets
+## Listing buckets
 
-Use `ListBucketsCommand` to inspect Buckets in the selected simulated S3 scope. Each Bucket reports the instant it was created, taken from [simulated time](https://yulinsim.dev/time/) rather than the host clock.
+`ListBucketsCommand` lists buckets in the selected account and region. Each bucket reports its
+creation time from the [simulated clock](https://yulinsim.dev/time/).
 
 ```typescript sim-s3-list-buckets
 /**
@@ -137,17 +136,20 @@ console.log(listBucketsOutput.Buckets?.map((bucket) => bucket.Name));
 console.log(listBucketsOutput.Buckets?.[0]?.CreationDate);
 ```
 
-## Asking whether something is there
+## Checking whether a bucket or object exists
 
-`HeadObjectCommand` reports what a read would say about an Object without returning the Object, and `HeadBucketCommand` reports whether a Bucket is there and reachable. `HeadBucket` also reports the Region it was found in.
+`HeadObjectCommand` returns object metadata without the body. `HeadBucketCommand` checks that a
+bucket exists and is accessible, and reports its region.
 
-A HEAD response carries no body, so there is no document for an error code to travel in. Real S3 answers a `HeadObject` with `403` or `404`, and a `HeadBucket` with `400`, `403` or `404`, leaving the SDK to name the failure from the status alone. The simulator answers `404` for an absent Bucket and an absent Object alike, which an SDK client raises as `NotFound`, and `403` for a caller the permission is missing for. A read distinguishes `NoSuchBucket` from `NoSuchKey`, because a read has a body to say which.
+A HEAD response has no error document. Yulin returns 404 for a missing bucket or object, which the
+SDK raises as `NotFound`. It returns 403 when the caller lacks permission. `GetObject` can distinguish
+`NoSuchBucket` from `NoSuchKey` because its error response has a body.
 
 `HeadObject` authorizes against `s3:GetObject` and `HeadBucket` against `s3:ListBucket`, as real S3 does, so knowing something is there needs the permission to read it.
 
-## Listing Objects
+## Listing objects
 
-Use `ListObjectsV2Command` to list the Objects in a Bucket. The simulator supports `Prefix`,
+Use `ListObjectsV2Command` to list objects in a bucket. Yulin supports `Prefix`,
 `Delimiter`, `MaxKeys`, `ContinuationToken` and `StartAfter`, and answers with `Contents`,
 `CommonPrefixes`, `KeyCount`, `IsTruncated` and `NextContinuationToken`.
 
@@ -197,18 +199,16 @@ for (const object of listedObjects) {
 }
 ```
 
-Listings are sorted by key, and a page holds at most 1,000 keys, as in real S3. `MaxKeys` above that
-is lowered to it, and the response reports the page size that was actually used. A `MaxKeys` of zero
-returns no keys and completes the listing, and a negative one is refused with `InvalidArgument`.
+Listings sort objects by key and return at most 1,000 entries. Larger `MaxKeys` values are capped at
+1,000. Zero returns an empty complete page, and a negative value raises `InvalidArgument`.
 
 A listing that found no keys has no `Contents` at all, and the example reaches for `Contents ?? []`
 for that reason. `KeyCount` is the count either way.
 
 ### Walking a truncated listing
 
-A truncated response carries `NextContinuationToken`, which the next request passes as
-`ContinuationToken`. The token is opaque, as it is in real S3. Pass it back unchanged, read nothing
-out of it, and simulated S3 refuses one it did not issue.
+A truncated response includes `NextContinuationToken`. Pass it unchanged as `ContinuationToken` in
+the next request. Yulin rejects tokens it did not issue.
 
 ```typescript sim-s3-list-objects-v2-pagination
 /**
@@ -533,9 +533,8 @@ An Object uploaded in parts gets a different form. See
 
 ## Uploading an Object in parts
 
-`aws s3 cp` switches to a multipart upload above eight megabytes, and `@aws-sdk/lib-storage` uploads
-in parts whatever the size. Sim S3 answers the six operations that path is made of, over the SDK and
-over a served endpoint alike.
+Yulin supports multipart upload through the SDK and served S3 endpoint. This covers the operations
+used by `aws s3 cp` for files above eight megabytes and by `@aws-sdk/lib-storage`.
 
 ```bash
 aws s3 cp ./big.bin s3://widgets/big.bin   # 12MB, multipart under the covers
@@ -846,9 +845,8 @@ See [Serve simulated S3 on localhost](#serve-simulated-s3-on-localhost) for sett
 
 ## Deleting Objects
 
-Use `DeleteObjectCommand` to remove one Object, and `DeleteObjectsCommand` to remove several in one
-request. Both are authorized against `s3:DeleteObject` on the Object ARN. A caller allowed to read a
-Bucket cannot empty it.
+Use `DeleteObjectCommand` to remove one object or `DeleteObjectsCommand` to remove several. Each
+object requires `s3:DeleteObject` permission on its ARN.
 
 ```typescript sim-s3-delete-object
 /**
@@ -931,9 +929,9 @@ failures come back.
 
 ## Object versioning
 
-A versioned Bucket keeps every write of a key instead of overwriting it, and answers a delete with a
-marker rather than removing anything. Turn it on with `PutBucketVersioningCommand`, or with
-`VersioningConfiguration` on an `AWS::S3::Bucket` resource.
+A versioned bucket keeps each write as a separate version. Deleting a key adds a delete marker. Enable
+versioning with `PutBucketVersioningCommand` or the `VersioningConfiguration` property of an
+`AWS::S3::Bucket`.
 
 ```typescript sim-s3-object-versioning
 import {
@@ -1096,12 +1094,11 @@ A delete on a versioned Bucket raises `s3:ObjectRemoved:DeleteMarkerCreated` rat
 
 ## Object Lock
 
-Object Lock holds a version of an Object against a delete. A version can be held by a retention
-period, by a legal hold or by both, and a delete naming a held version is answered with
-`AccessDenied`. One way past exists and it is narrow. A `GOVERNANCE` retention period gives way to a
-request carrying `BypassGovernanceRetention` from a caller allowed to use it. A `COMPLIANCE` period
-and a legal hold hold against everyone, the account root included. Turn it on with `PutObjectLockConfigurationCommand`, or with
-`ObjectLockEnabled` on an `AWS::S3::Bucket` resource.
+Object Lock protects an object version with a retention period, a legal hold, or both. Deleting a
+protected version raises `AccessDenied`. A caller with `s3:BypassGovernanceRetention` may bypass
+`GOVERNANCE` retention by setting `BypassGovernanceRetention`. `COMPLIANCE` retention and legal
+holds cannot be bypassed. Enable Object Lock with `PutObjectLockConfigurationCommand` or
+`ObjectLockEnabled` on an `AWS::S3::Bucket`.
 
 Object Lock holds a version, and versioning has to be on underneath it. Turning it on over a Bucket
 with versioning off is refused with `InvalidBucketState`, as real S3 refuses it, and a template
@@ -1256,8 +1253,8 @@ Bucket created around the property would report a default retention it never app
 
 ## Event notifications
 
-A simulated S3 Bucket can notify a simulated Lambda function, a simulated SQS queue or a simulated
-SNS topic when an Object is created or removed. The configuration is applied with
+A simulated bucket can notify Lambda, SQS or SNS when an object is created or removed. Apply the
+configuration with
 `PutBucketNotificationConfigurationCommand` and read back with
 `GetBucketNotificationConfigurationCommand`.
 
@@ -1360,10 +1357,10 @@ can take the `.jpg` files under a prefix while another takes the `.png` files un
 The rule applies across the destination groups. A function and a queue that both want the same
 event are refused as readily as two functions.
 
-`PutBucketNotificationConfigurationCommand` replaces the whole configuration rather than adding to
-it. `GetBucketNotificationConfigurationCommand` answers an empty configuration for a Bucket that has
-none. Note that the response carries the destination groups at the top level, while the request nests
-them under `NotificationConfiguration`:
+`PutBucketNotificationConfigurationCommand` replaces the complete configuration.
+`GetBucketNotificationConfigurationCommand` returns an empty configuration when none is set. The
+request nests destination groups under `NotificationConfiguration`, while the response puts them at
+the top level:
 
 ```typescript
 const read = await simAws
@@ -1476,9 +1473,9 @@ function is.
 
 ### To an SQS queue
 
-A `QueueConfigurations` entry names a queue by ARN. The whole `Records` document arrives as one
-message body, and a consumer parses `record.body` to get at the event. Put a Lambda event source
-mapping on the queue and the chain runs end to end after one `backgroundTasksComplete()`.
+A `QueueConfigurations` entry names a queue by ARN. S3 sends the complete `Records` document as one
+message body. Add a Lambda event source mapping to consume it, then call
+`backgroundTasksComplete()` to finish the delivery chain.
 
 The queue's `Policy` attribute has to allow `sqs:SendMessage` for the `s3.amazonaws.com` service
 principal. S3 supplies `aws:SourceArn` and `aws:SourceAccount`. The `ArnLike` condition CDK's
@@ -1633,10 +1630,9 @@ its own policy and its own Account's IAM are what admit the Bucket. A FIFO queue
 
 ### To an SNS topic
 
-A `TopicConfigurations` entry names a topic by ARN. The whole `Records` document is published as the
-SNS `Message`, with a `Subject` of `Amazon S3 Notification`, as real S3 publishes it. A queue
-subscribed to the topic therefore has two envelopes to reach through. Parse the message body for the
-SNS envelope, then parse its `Message` for the S3 event.
+A `TopicConfigurations` entry names a topic by ARN. S3 publishes the complete `Records` document as
+the SNS `Message` with the subject `Amazon S3 Notification`. A subscribed queue receives an SNS
+envelope whose `Message` contains the S3 event.
 
 The topic's `Policy` attribute has to allow `sns:Publish` for the `s3.amazonaws.com` service
 principal. S3 supplies `aws:SourceArn` and `aws:SourceAccount`. The `ArnLike` condition CDK's