@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/cloudwatch/README.md

@@ -1,20 +1,11 @@
 # Simulated CloudWatch Metrics
 
-Yulin includes a simulated Amazon CloudWatch for tests and local development. It holds custom
-metrics. Those are the datapoints `PutMetricData` publishes, and the statistics
-`GetMetricStatistics` and `GetMetricData` read back from them, without an AWS account. It also holds alarms over those
-metrics, which evaluate on the simulation's clock and notify an SNS topic when they change state.
-
-Code that publishes a business metric is code teams already have, and until now the only way to test
-it was to assert that the SDK client had been called. That proves the call was made. What it
-measured goes untested.
-
-Most of what lives here is custom metrics. Simulated Lambda publishes its own `AWS/Lambda`
-`Invocations`, `Errors`, `Duration` and `IteratorAge`, simulated Cognito publishes a pool's
-`AWS/Cognito` counts, and no other simulated service publishes into an `AWS/` namespace yet. A
-query for one nothing measures comes back empty, in place of a number that was never taken. A test
-can stand a datapoint up for one of those itself, which is what drives an alarm on a service metric
-to a state change.
+Yulin simulates CloudWatch metrics and alarms in memory. Application code can publish datapoints and
+read their statistics through the normal CloudWatch commands. Alarms evaluate on simulated time and
+can notify simulated SNS topics.
+
+Simulated Lambda publishes `AWS/Lambda` metrics, and simulated Cognito publishes `AWS/Cognito`
+metrics. Tests can seed other AWS-managed metrics through the service writer described below.
 
 A custom metric's datapoints arrive either from `PutMetricData` or from a CloudWatch Logs metric
 filter counting matching log events. See the [CloudWatch Logs docs](../logs/README.md) for the
@@ -24,8 +15,8 @@ CloudWatch specific types are imported from the `@kensio/yulin/cloudwatch` subpa
 
 ## Publishing and reading back a metric
 
-A metric is identified by its namespace, its name and its dimensions together. Publishing a value
-and asking for it back at a period is the whole loop:
+A metric is identified by its namespace, name, and exact set of dimensions. Publish a value and
+read it back over a period:
 
 ```typescript sim-cloudwatch-publish-and-read
 /**
@@ -84,18 +75,14 @@ the way out. A query naming a unit CloudWatch lacks fails here as it would in an
 
 ## Metrics are identified by their dimensions
 
-Real CloudWatch leaves a custom metric unrolled across its dimensions, and so does this. The same
-metric name published under two channels is two metrics. A read naming no dimensions reaches only the
-metric that was published with none, and never aggregates across the others.
-
-That is the behaviour teams most often get wrong, and it is worth a test of its own. A dashboard
-query written against a metric name alone finds nothing at all if every publish carried a dimension.
+CloudWatch treats each exact set of dimensions as a separate metric. Publishing the same metric name
+with two dimension values creates two metrics. A query without dimensions reads only datapoints
+published without dimensions.
 
 ## Metrics and simulated time
 
-A datum carrying no `Timestamp` is stamped from the simulation's clock. A test with
-a frozen clock therefore gets timestamps it can assert on exactly, and one that moves time on gets
-datapoints in the period it moved to:
+A datum without a `Timestamp` uses the simulation's clock. Set or advance the clock to place
+datapoints in exact periods:
 
 ```typescript sim-cloudwatch-simulated-time
 /**
@@ -153,11 +140,14 @@ window drops a metric out of the listing without anything having to expire it.
 
 ## Metrics a simulated service publishes
 
-Real CloudWatch holds two kinds of metric. A caller publishes a custom one through `PutMetricData`, and AWS publishes its own under a namespace beginning `AWS/` that no caller may write into. Both kinds are read the same way.
+Callers publish custom metrics through `PutMetricData`. AWS-managed metrics use namespaces beginning
+with `AWS/`, which callers cannot publish into.
 
-Two services publish their own. Simulated Cognito counts what a user pool was asked to do, under `AWS/Cognito` and dimensioned by `UserPool` and `UserPoolClient`, which the [Cognito docs](../cognito/README.md) cover.
+Simulated Cognito publishes counts under `AWS/Cognito`, dimensioned by `UserPool` and
+`UserPoolClient`. See the [Cognito docs](../cognito/README.md).
 
-Simulated Lambda publishes three of its own. Every invocation counts `Invocations` and a `Duration`, and one whose handler threw counts an `Errors` alongside them, all under `AWS/Lambda` and dimensioned by `FunctionName`. Nothing has to be turned on, and no execution Role needs a permission for it, which is how real Lambda behaves.
+Simulated Lambda publishes `Invocations`, `Duration`, and `Errors` under `AWS/Lambda`, dimensioned by
+`FunctionName`. These metrics require no extra configuration or execution-role permission.
 
 ```typescript sim-cloudwatch-lambda-errors
 /**
@@ -217,13 +207,15 @@ const { MetricAlarms } = await simAws
 console.log(MetricAlarms?.[0]?.StateValue);
 ```
 
-`Duration` is measured on the simulation's clock rather than the host's, so it is a number a test can assert on. A handler that moves the clock reports the time it moved, and one that returns without touching it reports nothing spent. `IteratorAge` is measured the same way, and the Lambda documentation covers what a stream event source mapping reports.
+`Duration` uses the simulation's clock rather than the host's. A handler that advances the clock
+reports that elapsed time, while a handler that leaves it unchanged reports zero duration.
+`IteratorAge` uses the same clock. The Lambda documentation describes the value reported by a stream
+event source mapping.
 
 ## Seeding a metric AWS publishes
 
-`PutMetricData` refuses a namespace beginning `AWS/`, exactly as an account does. An alarm watching a metric no simulated service publishes therefore sits in `INSUFFICIENT_DATA`, and its arithmetic goes untested however carefully the alarm itself is declared.
-
-The service writer is the way in. It is the same route simulated Lambda's own metrics take, reached from a test through `cloudWatch().serviceWriter()`, and it stands a datapoint up in any namespace.
+`PutMetricData` refuses namespaces beginning with `AWS/`. To test an alarm for another AWS-managed
+metric, add the datapoint through `cloudWatch().serviceWriter()`.
 
 ```typescript sim-cloudwatch-seed-service-metric
 /**
@@ -286,14 +278,13 @@ console.log(MetricAlarms?.[0]?.StateValue);
 
 A datapoint arriving without a `timestamp` is stamped with the simulation's clock. One carrying its own lands where it says, which fills a window without the clock having to be walked through it.
 
-`PutMetricData` is untouched by any of this. A caller naming a reserved namespace is refused exactly as before, and only the account's own machinery and a test reach the store this way.
+The service writer is a test setup API. `PutMetricData` keeps its reserved-namespace validation.
 
 ## Alarms
 
-An alarm watches one metric and changes state on the simulation's clock, with no real timer behind
-it. Each evaluation is scheduled at the next period boundary. A frozen clock evaluates nothing, and
-advancing time by twenty minutes walks twenty one-minute evaluations and settles before the next
-line of the test runs.
+An alarm watches one metric and changes state on the simulation's clock. Each evaluation is scheduled
+at the next period boundary. Advancing time by twenty minutes runs twenty one-minute evaluations and
+settles before the next line of the test.
 
 ```typescript sim-cloudwatch-alarm
 /**
@@ -353,8 +344,8 @@ console.log(described.MetricAlarms?.at(0)?.StateValue);
 ```
 
 A new alarm is in `INSUFFICIENT_DATA` until it has evaluated a period, as on real CloudWatch. The
-window it looks back over reaches behind the moment the alarm was created. An alarm over a metric
-nothing publishes into, with `TreatMissingData: "breaching"`, therefore fires on its first
+window it looks back over reaches behind the moment the alarm was created. An alarm over an empty
+metric, with `TreatMissingData: "breaching"`, therefore fires on its first
 evaluation, without waiting for the periods to accumulate. That is what an account does too.
 
 ### Reaching a subscriber
@@ -458,10 +449,9 @@ had never named them.
 
 ## Permissions
 
-CloudWatch metrics have no ARN, leaving a policy nothing to name. Every metric action here is
-granted on `*`. A policy written against something like
-`arn:aws:cloudwatch:eu-west-2:111111111111:metric/Orders/Failed` reaches nothing, here and in an
-account.
+CloudWatch metrics have no ARN, so every metric action uses a resource of `*`. A policy written
+against a fabricated metric ARN such as
+`arn:aws:cloudwatch:eu-west-2:111111111111:metric/Orders/Failed` is invalid in Yulin and AWS.
 
 Alarms are the exception, and do have an ARN. `PutMetricAlarm`, `DeleteAlarms` and `SetAlarmState`
 authorize against `arn:aws:cloudwatch:<region>:<account>:alarm:<name>`, while `DescribeAlarms` and
@@ -525,7 +515,7 @@ await simAws.cloudWatch().putMetricData(
 // Publishing into any other namespace as this Role is denied.
 ```
 
-## What is simulated
+## Supported operations
 
 - `PutMetricData`, with `Value`, `StatisticValues` and `Values`/`Counts`.
 - `ListMetrics`, filtered by namespace, metric name and dimensions, with `RecentlyActive` and
@@ -546,11 +536,9 @@ await simAws.cloudWatch().putMetricData(
 - `AWS::CloudWatch::Alarm` in simulated CloudFormation, deployed through `PutMetricAlarm` and taken
   down with the stack.
 
-## What is refused, and how it says so
+## Unsupported operations and options
 
-Anything real CloudWatch would accept and this leaves undone is refused with a message saying so,
-rather than accepted and ignored. A silently dropped filter is worse than a failure, because the
-test still passes and no longer means what it says.
+Yulin rejects unsupported CloudWatch behavior instead of ignoring it:
 
 - **Composite and anomaly detection alarms.** `Metrics` and `ThresholdMetricId` on `PutMetricAlarm`
   are refused. There is no trained model here for an anomaly band to come from.
@@ -571,8 +559,6 @@ test still passes and no longer means what it says.
   through the service writer. A CloudWatch Logs metric filter naming a reserved namespace is refused
   when it publishes, as `PutMetricData` refuses a caller naming one.
 
-Two divergences are deliberate, and not refusals. Real CloudWatch rejects a datapoint more than two
-weeks old or more than two hours in the future, and this accepts any timestamp, letting a test seed
-a window without arranging the clock around it. And datapoints come back earliest first, which real
-CloudWatch's contract permits without promising, because a test reading the third period of five
-needs an order it can rely on.
+Two behaviors differ from AWS. Yulin accepts datapoints more than two weeks old or more than two
+hours in the future, which makes it easier to seed a test window. It also returns datapoints in
+ascending timestamp order so tests receive deterministic results.

package/docs/services/cognito/README.md

@@ -1,17 +1,14 @@
 # Simulated Cognito IDP
 
-Yulin includes a simulated Cognito user pool directory for tests and local development. Pools and
-their app clients are held in memory, and every operation is authorized by simulated IAM.
+Yulin simulates Cognito user pools, app clients, users, groups, tokens, hosted domains and Lambda
+triggers. Use `simAws.cognitoIdp()` directly or intercept a `CognitoIdentityProviderClient`.
+Cognito types are available from `@kensio/yulin/cognito`.
 
-Only user pools are simulated. Cognito identity pools, which exchange a token for AWS credentials,
-are a different service and are outside the simulation.
-
-Cognito-specific types are imported from the `@kensio/yulin/cognito` subpath.
+Cognito identity pools are unsupported.
 
 ## Creating a pool and an app client
 
-A pool needs a name. Everything else has a default, and the defaults here are the ones real Cognito
-applies.
+A user pool needs a name. Other properties use Cognito's defaults.
 
 ```typescript sim-cognito-create-user-pool
 /**
@@ -46,16 +43,14 @@ const appClient = await cognito.createUserPoolClient(
 console.log(appClient.UserPoolClient?.ClientId); // 26 lowercase characters
 ```
 
-A pool id names the region the pool was created in, as real pool ids do. Application code that
-splits the id on the underscore to find the region works here for the same reason it works on AWS.
+A pool ID contains the region before its underscore, matching Cognito's ID format.
 
 Two pools may share a name. Only the id identifies one.
 
 ## Password policy
 
-A pool created without a `Policies` of its own gets the real default of eight characters, with an
-uppercase letter, a lowercase letter, a number and a symbol each required. A request setting some of
-those keeps the defaults for the rest.
+A pool created without `Policies` requires at least eight characters with uppercase, lowercase,
+numeric and symbol characters. Setting part of the policy keeps the defaults for omitted fields.
 
 ```typescript sim-cognito-password-policy
 /**
@@ -86,10 +81,9 @@ with `InvalidPasswordException`, saying which rule it broke.
 
 ## Users
 
-`AdminCreateUser` creates a user in `FORCE_CHANGE_PASSWORD`, where real Cognito leaves a user an
-admin made. It has a temporary password and cannot sign in with it. Setting a permanent password
-moves the user to `CONFIRMED`. The sign-in flows read that status. A user in
-`FORCE_CHANGE_PASSWORD` gets the `NEW_PASSWORD_REQUIRED` challenge, not tokens.
+`AdminCreateUser` creates a user in `FORCE_CHANGE_PASSWORD` with a temporary password. Sign-in
+returns the `NEW_PASSWORD_REQUIRED` challenge until `AdminSetUserPassword` sets a permanent
+password. A permanent password changes the status to `CONFIRMED`.
 
 ```typescript sim-cognito-create-user
 /**
@@ -145,11 +139,9 @@ console.log(read.UserAttributes?.find((each) => each.Name === "sub")?.Value);
 A password set without `Permanent: true` is temporary, and leaves the user in
 `FORCE_CHANGE_PASSWORD` again.
 
-A user's `sub` is a UUID Cognito allocates, reported among its attributes. It is not the username,
-and code treating the two as interchangeable fails here, and not in a deployment. Admin
-operations here name a user by its username only. Real Cognito also accepts a `sub` where an
-operation asks for a username. That is one thing that works there and not here. The refusal says so
-when the username given is some user's `sub`.
+A user's `sub` is a generated UUID and differs from the username. Yulin's admin operations accept
+the username only. Cognito also accepts a `sub` for some operations, which Yulin reports as an
+unsupported lookup.
 
 Attributes come back under `Attributes` from `AdminCreateUser` and `ListUsers`, and under
 `UserAttributes` from `AdminGetUser`, as the real API names them.
@@ -160,11 +152,9 @@ Attributes come back under `Attributes` from `AdminCreateUser` and `ListUsers`,
 
 ## Signing in by email or phone number
 
-A pool created with `UsernameAttributes` signs its users in by that attribute, not by a username
-they chose. Cognito generates a UUID as the username for such a user, and the value the
-request called the username goes into the attribute the pool signs in by. That generated username
-is what `AdminGetUser` reports and what the `cognito:username` claim carries. An application reading
-"the username" off such a pool reads a UUID.
+A pool with `UsernameAttributes` signs users in with an email address or phone number. Cognito
+generates a UUID for the stored username. `AdminGetUser` and the `cognito:username` token claim
+report that UUID.
 
 A CDK `UserPool` with `signInAliases: { email: true }` emits `UsernameAttributes: ["email"]`, the
 usual way to build an email sign-in pool.
@@ -384,13 +374,11 @@ outside the simulation.
 
 ## Signing up
 
-`SignUp` is the other way a user gets into a pool. It names an app client rather than a pool, is
-authorized by no IAM policy, and leaves the user in `UNCONFIRMED` with the password it chose.
+`SignUp` creates an `UNCONFIRMED` user through an app client. The operation does not use IAM
+authorization.
 
-Real Cognito emails or texts a confirmation code at that point. Nothing here delivers a message, and
-the code is readable from the pool instead, through `confirmationCode` on the pool object. That is a
-deliberate divergence. Real Cognito never reports a code back to anyone, and reading one is what
-makes a registration flow testable at all.
+Read the confirmation code from `confirmationCode` on the simulated pool. Cognito sends the code by
+email or text and never exposes it through the service API.
 
 The pool also records the message it would have sent, holding the wording and the code a user
 would have read. That is in [Messages a pool would have sent](#messages-a-pool-would-have-sent)
@@ -500,9 +488,8 @@ the deployed pool would give. A pool created without the setting allows sign-up,
 
 ## Resetting a forgotten password
 
-A user that cannot get in asks for a code with `ForgotPassword` and sets a new password with
-`ConfirmForgotPassword`. Both name an app client, and neither is authorized by an IAM policy. They
-are the pair an application calls when it has built its own sign-in screens.
+`ForgotPassword` sends a code and `ConfirmForgotPassword` sets the new password. Both operations use
+an app client and bypass IAM authorization.
 
 The code goes to the same place a sign-up code goes, and is read back the same way, through
 `confirmationCode` on the pool object. `ForgotPassword` answers with `CodeDeliveryDetails` naming
@@ -633,9 +620,8 @@ are refused for one.
 
 ## Messages a pool would have sent
 
-Nothing here delivers an email or a text message. A pool records what it would have sent instead,
-and `sentMessages` on the pool object hands the record over. Each message carries the recipient, the
-medium, the subject, the body and the occasion it was sent on.
+The pool records outgoing email and text messages in `sentMessages`. Each entry contains the
+recipient, medium, subject, body and message type.
 
 A message is recorded on five occasions. Those are a `SignUp`, a `ResendConfirmationCode`, an
 `AdminCreateUser` that did not ask for `MessageAction: SUPPRESS`, an MFA code sent by text message,
@@ -2060,10 +2046,9 @@ own users at the same address, which real Cognito keeps as two accounts until
 `AdminLinkProviderForUser` merges them. That operation is unsimulated.
 
 Posting the page carries on into the sign-in the authorize endpoint already runs, ending in the same
-`<ProviderName>_<subject>` user and the same authorization code. Nothing is kept on the provider
-afterwards: a further authorize request asks again, because real Cognito asks the provider afresh
-every time. A provider that `signInAs` has already put somebody at skips the page, which is what
-leaves a test that says who is signing in seeing none of this.
+`<ProviderName>_<subject>` user and the same authorization code. Provider state is discarded after
+the request. A later authorize request asks again because real Cognito asks the provider afresh each
+time. A provider configured with `signInAs` skips the page and uses the configured identity.
 
 `/signup` is a link from that page. Its form asks for a username, a password and the attributes the
 pool needs, which are the ones its `Schema` made required and the ones its `AutoVerifiedAttributes`
@@ -3704,8 +3689,8 @@ console.log(described.UserPoolClient?.ClientName);
 
 A registered pool behaves like any other. It answers `DescribeUserPoolCommand` and
 `ListUserPoolsCommand`, holds users, groups and app clients, and serves its JWKS and OpenID
-configuration on localhost. Everything written against a pool id follows from the id it was
-registered under: its ARN, its issuer URL, the `iss` claim of its tokens and its `ProviderName`. A
+configuration on localhost. The registered ID determines the pool ARN, issuer URL, token `iss` claim
+and `ProviderName`. A
 policy naming `arn:aws:cognito-idp:eu-west-2:111111111111:userpool/eu-west-2_aBcDeFgHi` authorizes
 the handler that reads the pool, which is what a template carrying the id in two places needs.
 

package/docs/services/dynamodb/README.md

@@ -1,18 +1,13 @@
 # Simulated DynamoDB
 
-Yulin includes a simulated DynamoDB for tests and local development. Tables are held in memory, and
-every operation is authorized by simulated IAM.
-
-This page covers creating, describing, listing and deleting tables. What a request says is checked
-the way real DynamoDB checks it. A table that can be created here is one that could be created on
-AWS.
-
-DynamoDB-specific types are imported from the `@kensio/yulin/dynamodb` subpath.
+Yulin simulates DynamoDB tables, indexes, items, streams and time to live in memory. Use
+`simAws.dynamoDb()` directly or intercept a `DynamoDBClient`. DynamoDB types are available from
+`@kensio/yulin/dynamodb`.
 
 ## Creating a table
 
-`CreateTable` needs a `TableName`, a `KeySchema`, and an `AttributeDefinitions` entry for every
-attribute the key schema names.
+`CreateTable` requires a table name, a key schema and an attribute definition for every key
+attribute.
 
 ```typescript sim-dynamodb-create-table
 /**
@@ -45,8 +40,7 @@ await simAws.backgroundTasksComplete();
 A new table is `CREATING`, and activation is scheduled as background work. Call
 `simAws.backgroundTasksComplete()` when a test needs the table to be `ACTIVE`.
 
-The description carries back what the request asked for. That is the key schema, the attribute
-definitions, the table ARN, a table ID, and the billing and capacity the table was created with.
+The response describes the table's keys, attribute definitions, ARN, ID, billing mode and capacity.
 
 ## Key schema and attribute definitions
 
@@ -62,9 +56,8 @@ attribute as the type the table declared for it.
 
 ## Billing modes and throughput
 
-`BillingMode` defaults to `PROVISIONED`, making `ProvisionedThroughput` required with at least one
-read and one write capacity unit. A request that leaves both out asks for a provisioned table with
-no capacity, and is refused.
+`BillingMode` defaults to `PROVISIONED`. A provisioned table requires at least one read and one write
+capacity unit in `ProvisionedThroughput`.
 
 `PAY_PER_REQUEST` refuses `ProvisionedThroughput`, since an on-demand table has no capacity to
 provision.
@@ -111,8 +104,8 @@ reports for one.
 
 ## Global secondary indexes
 
-`GlobalSecondaryIndexes` on `CreateTable` declares indexes with a key of their own over the same
-items. Each index needs an `IndexName`, a `KeySchema` and a `Projection`.
+`GlobalSecondaryIndexes` adds indexes over the table's items. Each index requires an `IndexName`,
+`KeySchema` and `Projection`.
 
 ```typescript sim-dynamodb-global-secondary-index
 /**
@@ -583,9 +576,8 @@ console.log(description.Table?.TableStatus); // "ACTIVE"
 
 ## Tagging tables
 
-A table is tagged by `CreateTable`, or afterwards by `TagResource`. `UntagResource` takes tags off,
-and `ListTagsOfResource` reads them back. The three tag commands name their resource by ARN, in
-`ResourceArn`, where the table commands take a name or an ARN.
+Add tags during `CreateTable` or later with `TagResource`. Remove them with `UntagResource` and read
+them with `ListTagsOfResource`. Tag commands require the table ARN in `ResourceArn`.
 
 ```typescript sim-dynamodb-tag-table
 /**
@@ -683,9 +675,8 @@ calling `Tags.of(stack).add("Environment", "test")` gets a tagged table.
 
 ## Writing items
 
-`PutItem` writes one item, replacing the whole item under its primary key rather than merging into
-it. The item is there by the time the call returns. A write and the read that follows it need no
-step in between.
+`PutItem` replaces the complete item stored under the primary key. The write is visible when the
+command returns.
 
 ```typescript sim-dynamodb-put-item
 /**
@@ -739,10 +730,9 @@ anywhere else in the item.
 
 ## Reading and deleting items
 
-`GetItem` reads one item by its primary key, and `DeleteItem` removes one the same way. The `Key`
-both take is the whole primary key and nothing else. A missing key element, an attribute outside the
-key, or a value whose type fails to match the table's `AttributeDefinitions` is a
-`ValidationException` naming the attribute at fault.
+`GetItem` reads an item by primary key. `DeleteItem` removes it. The `Key` must contain every key
+attribute and no others, using the types declared in `AttributeDefinitions`. Invalid keys raise
+`ValidationException`.
 
 ```typescript sim-dynamodb-get-delete-item
 /**
@@ -822,9 +812,8 @@ Both take the table's name or its ARN, as the table commands do.
 
 ## Updating items
 
-`UpdateItem` changes part of an item, where `PutItem` replaces the whole thing. What to change is
-written as an `UpdateExpression` made of `SET`, `REMOVE`, `ADD` and `DELETE` clauses, in any order.
-Each keyword appears at most once, and the actions inside a clause are separated by commas.
+`UpdateItem` changes selected attributes. Its `UpdateExpression` may contain `SET`, `REMOVE`, `ADD`
+and `DELETE` clauses in any order. Each clause may appear once and contain comma-separated actions.
 
 A `SET` action is `path = operand`, where an operand is a value from `ExpressionAttributeValues`,
 another document path, or a call to `if_not_exists(path, operand)` or `list_append(one, other)`. Two
@@ -1066,12 +1055,11 @@ placeholder used by either counts as used.
 
 ## Conditional writes
 
-`PutItem`, `DeleteItem` and `UpdateItem` take a `ConditionExpression`, checked against whatever is
-stored under the key before anything changes. A condition that fails to hold leaves the item exactly
-as it was and throws `ConditionalCheckFailedException`, with the name and message real DynamoDB
-uses.
+`PutItem`, `DeleteItem` and `UpdateItem` evaluate `ConditionExpression` against the stored item before
+writing. A failed condition leaves the item unchanged and raises
+`ConditionalCheckFailedException`.
 
-That is how a write becomes an insert if absent, and how a version attribute becomes optimistic
+Use `attribute_not_exists` for insert-only writes or compare a version attribute for optimistic
 locking.
 
 ```typescript sim-dynamodb-conditional-write
@@ -1176,9 +1164,8 @@ expression, in both directions. A placeholder the request leaves undefined is a
 
 ## Projecting attributes
 
-`GetItem` takes a `ProjectionExpression`, a comma-separated list of document paths. Only those paths
-come back. A path is an attribute name, then any number of `.attribute` dereferences and `[n]` list
-indexes, such as `address.city` or `lines[0].sku`.
+`ProjectionExpression` is a comma-separated list of document paths returned by `GetItem`. A path can
+contain map attributes and list indexes, such as `address.city` or `lines[0].sku`.
 
 An attribute name that is a DynamoDB reserved word, or that has a character an expression cannot
 carry, is written as a `#name` placeholder and defined in `ExpressionAttributeNames`.
@@ -1259,12 +1246,11 @@ index and a path past that depth are each a `ValidationException` naming the pat
 
 ## Querying an item collection
 
-A table with a sort key holds an item collection under each partition key, holding the items with
-that partition key, ordered by their sort key. `Query` reads one of those collections.
+A table with a sort key keeps one ordered item collection per partition key. `Query` reads one
+collection.
 
-`KeyConditionExpression` says which. It is one equality on the partition key, optionally joined by
-`AND` to one condition on the sort key. The sort key condition is `=`, `<`, `<=`, `>`, `>=`,
-`BETWEEN` or `begins_with`, and both bounds of a `BETWEEN` are inside the range.
+`KeyConditionExpression` requires equality on the partition key. It may add one sort key condition
+with `AND`. Sort key operators are `=`, `<`, `<=`, `>`, `>=`, `BETWEEN` and `begins_with`.
 
 ```typescript sim-dynamodb-query
 /**
@@ -1371,8 +1357,8 @@ in `ExpressionAttributeNames`, as in any other expression.
 
 ### Paging a collection
 
-`Limit` counts the items a query evaluated. `LastEvaluatedKey` is the primary key of the item the
-walk stopped on, and the next request passes it back as `ExclusiveStartKey` to resume after it.
+`Limit` counts evaluated items. Pass `LastEvaluatedKey` back as `ExclusiveStartKey` to continue after
+the last evaluated item.
 
 ```typescript sim-dynamodb-query-paging
 /**
@@ -1447,9 +1433,7 @@ from a different partition key is refused, since it names a collection this quer
 
 ## Reading a global secondary index
 
-`IndexName` on `Query` and `Scan` reads an index in place of the table. The key condition is held to
-the index key schema and not the table's, which is the point. The index is how an access pattern the
-table key cannot serve gets served.
+Set `IndexName` on `Query` or `Scan` to read an index. Key conditions then use the index key schema.
 
 ```typescript sim-dynamodb-query-index
 /**
@@ -1572,9 +1556,8 @@ refused.
 
 ## Scanning a table
 
-`Scan` reads every item in a table. It needs no key knowledge at all. That is what makes it the
-operation test setup and assertions reach for, and the wrong operation for most application access
-patterns, since it reads the whole table however few items the caller wanted.
+`Scan` reads every item in a table without a key condition. It is useful for test assertions but
+usually reads more data than application code needs.
 
 ```typescript sim-dynamodb-scan
 /**