@kensio/yulin 1.21.7 → 1.21.8

package/docs/services/ecs/README.md

@@ -1,31 +1,20 @@
 # Simulated ECS
 
-Yulin includes a simulated Amazon ECS for tests and local development. It holds clusters, task
-definitions and services in memory, runs tasks from handlers you bind to their containers, and
-authorizes every operation with simulated IAM.
+Yulin simulates ECS clusters, task definitions, tasks and services. It runs JavaScript or TypeScript
+handlers bound to container image URIs. Use `simAws.ecs()` directly or intercept an `ECSClient`.
+ECS types are available from `@kensio/yulin/ecs`.
 
-ECS-specific types are imported from the `@kensio/yulin/ecs` subpath.
+## Binding code to a container image
 
-## What Yulin does with a container image
+Yulin uses an image URI as an identifier for an in-process handler. It does not pull or execute the
+image. A container with a matching binding runs the handler. An unbound container is recorded as
+unsimulated while the rest of the task continues.
 
-Yulin never looks inside a container image, and it could not if it tried. An image may hold a Go
-binary, nginx, Redis or anything else, and the only thing Yulin can run is JavaScript or TypeScript
-in its own process.
+A task definition may include application and support containers. Yulin stores and reports every
+container, but only runs containers that have a binding.
 
-So an image URI is only ever an identifier. Nothing here reads it, pulls it, or runs anything from
-it. It is stored as declared, and it is what a container is matched on when a task runs, in the same
-way an image URI identifies a container image Lambda function. The rule that follows is that a
-container matched to a handler runs that handler, and a container with no match is recorded as not
-simulated while the rest of the task carries on.
-
-A realistic task definition holds an application container, a log router and an observability agent.
-Only the first of those is something Yulin could ever run, and all three are stored and reported
-back exactly as declared.
-
-The case this leaves out is a sidecar the application depends on, such as a Redis or a database in
-the same task. Point its connection details, which are ordinary environment variables, at a real one
-you run yourself. See [non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/) for how that fits
-together.
+Run required sidecars such as Redis separately and pass their connection details through environment
+variables. See [non-AWS dependencies](https://yulinsim.dev/non-aws-dependencies/).
 
 ## Registering a task definition
 
@@ -76,9 +65,7 @@ console.log(described.taskDefinition?.containerDefinitions?.[0]?.image);
 // "example.dkr.ecr.eu-west-2.amazonaws.com/checkout:1"
 ```
 
-Container definitions are stored as declared, whatever the image is and whether or not Yulin could
-ever run it. That covers port mappings, environment variables and secrets. A `valueFrom` naming a
-Secrets Manager secret is held as the identifier it is, and never resolved.
+Container definitions retain their images, port mappings, environment variables and secrets.
 
 A registration that declares something this simulation has no room for is refused outright, and
 never trimmed. That way a declaration cannot go missing from the revision it made.
@@ -132,9 +119,8 @@ a full task definition ARN. The ARN of a revision is
 
 ## Deregistering a revision
 
-`DeregisterTaskDefinition` marks one revision `INACTIVE` without removing it. It stays describable
-by `family:revision` and by ARN, because something already holding either of those still needs to
-find out what it declared. What it stops being is the revision the family resolves to.
+`DeregisterTaskDefinition` marks a revision `INACTIVE` without removing it. The revision remains
+available by `family:revision` or ARN, but the family name no longer resolves to it.
 
 ```typescript sim-ecs-deregister-task-definition
 /**
@@ -234,8 +220,8 @@ A family counts as inactive once every one of its revisions has been deregistere
 
 ## Clusters
 
-A cluster is a named scope for the tasks and services that will run in it. `CreateCluster`,
-`DescribeClusters`, `ListClusters` and `DeleteCluster` hold them.
+A cluster contains tasks and services. Use `CreateCluster`, `DescribeClusters`, `ListClusters` and
+`DeleteCluster` to manage it.
 
 ```typescript sim-ecs-clusters
 /**
@@ -290,13 +276,13 @@ A cluster is named either by its short name or by its full ARN, and the two are
 ARN belonging to another account or region names a different cluster. `DescribeClusters` reports it
 as a `MISSING` failure, and `DeleteCluster` refuses it.
 
-A cluster has to exist before a task can run in it, including the `default` one. Yulin creates no
-cluster on its own, so create the one the tasks run in.
+Create a cluster before running a task. This includes the `default` cluster, which Yulin does not
+create automatically.
 
 ## Running a task
 
-`bindContainer` says what a container runs. `RunTask` then starts a task in a cluster, and the bound
-handlers run in this process.
+`bindContainer` associates an image with a handler. `RunTask` starts the task and schedules bound
+handlers to run in process.
 
 ```typescript sim-ecs-run-task
 /**
@@ -376,9 +362,7 @@ The task stops with a `stopCode` of `TaskFailedToStart` saying that nothing ran.
 
 ### Binding by image repository
 
-A container built by CDK or by a pipeline has an image tag that changes with every build, so naming
-the container by hand is the wrong way round. A binding can name the repository instead, and the tag
-is ignored on both sides.
+Use a repository binding when image tags change between builds. Repository matching ignores the tag.
 
 ```typescript sim-ecs-bind-image-repository
 /**
@@ -505,9 +489,8 @@ Read inside the handler to get the container's own.
 
 ## The task role
 
-While a container runs, its AWS calls are attributed to the task definition's `taskRoleArn`, in the
-same way a sim Lambda function's are to its execution role. Calls made through an SDK client
-intercepted by `SimSdk` pick this up without the code under test knowing.
+AWS calls made by a container use the task definition's `taskRoleArn`. An SDK client intercepted by
+`SimSdk` picks up the role from the running handler.
 
 ```typescript sim-ecs-task-role
 /**
@@ -600,10 +583,8 @@ alone, since there is no image to pull and no log driver to write to.
 
 ## Container secrets
 
-A container definition's `secrets` are resolved when the task starts, from simulated Secrets Manager
-or simulated SSM Parameter Store according to what each `valueFrom` names, and the values appear in
-the container's environment alongside its declared `environment`. A handler reads them through
-`process.env` like anything else.
+Yulin resolves container `secrets` from simulated Secrets Manager or SSM Parameter Store when the
+task starts. The values appear in `process.env` alongside the declared environment variables.
 
 They are read as the task definition's `executionRoleArn` rather than its `taskRoleArn`. That is the
 split real ECS makes. The execution role is what the task agent pulls secrets with before a
@@ -765,8 +746,7 @@ is reported as it stands, keeping the reason it stopped for.
 
 ## Services
 
-A task runs and stops. A service keeps tasks running, and that is what a deployed application
-usually is. It is a named service in a cluster, running some number of tasks from a task definition.
+An ECS service maintains a desired number of tasks from one task definition in a cluster.
 
 `CreateService` creates one. Its tasks exist as soon as the request is answered and reach `RUNNING`
 on the simulation's background work, as real ECS brings a new service up. The service reports the

package/docs/services/elbv2/README.md

@@ -1,24 +1,16 @@
 # Simulated Elastic Load Balancing
 
-Yulin includes a simulated Application Load Balancer for tests and local development. Load
-balancers, target groups, listeners and listener rules are held in memory and every operation is
-authorized by simulated IAM. ELBv2-specific types are imported from the `@kensio/yulin/elbv2`
-subpath.
-
-A load balancer created here has a DNS name of the shape real ELB issues, and a
-[Route53](https://yulinsim.dev/services/route53/) record pointing at that name resolves to it. A request made to your own
-hostname reaches the load balancer as it would deployed. A request is matched to a listener by port
-and then to one of that listener's rules, and a `forward` action sends it to a target group, where a
-registered [Lambda](https://yulinsim.dev/services/lambda/) function is invoked with the request and its response becomes the
-HTTP response.
-
-Only the application load balancer is simulated. A network or gateway load balancer routes below
-HTTP, which nothing here speaks, and `Type: "network"` is refused outright.
-
-No TLS is performed anywhere in this. An HTTPS listener holds a certificate and is checked against
-simulated ACM, and everything travels in the clear. See
-[HTTPS listeners and certificates](#https-listeners-and-certificates) for what that leaves a test
-able to conclude.
+Yulin simulates Application Load Balancers, target groups, listeners and listener rules for tests
+and local development. Requests pass through the listener and rule configuration before reaching a
+registered Lambda function or simulated ECS service. Simulated IAM authorizes every operation.
+
+Each load balancer receives an AWS-shaped DNS name. A simulated
+[Route 53](https://yulinsim.dev/services/route53/) record can point a local hostname at that name, so
+an HTTP request follows the same routing path as the deployed application.
+
+Network and Gateway Load Balancers are not simulated. HTTPS listeners validate their certificates
+against simulated ACM, but Yulin does not perform TLS. Import ELBv2-specific types from
+`@kensio/yulin/elbv2`.
 
 ## Creating a load balancer
 
@@ -73,9 +65,8 @@ why a load balancer cannot be named starting with `internal-`.
 
 ## Target groups hold functions or addresses
 
-A target group names what it holds through its `TargetType`, and that decides the rest. It sets how
-many targets the group takes, what a target's `Id` has to look like, and whether the group carries a
-protocol and port at all.
+`TargetType` determines what a target group can contain. It controls the number and shape of target
+IDs, and whether the group requires a protocol and port.
 
 ```typescript sim-elbv2-lambda-target-group
 /**
@@ -178,15 +169,14 @@ console.log(health.TargetHealthDescriptions?.length); // 1
 console.log(health.TargetHealthDescriptions?.[0]?.Target.Port); // 8080
 ```
 
-`TargetType: "instance"` is refused outright, because there are no EC2 instances here for it to mean
-anything about. A group created as one would look configured and route nowhere. A request naming no
-target type at all is refused for the same reason, since real ELB defaults it to `instance`.
+`TargetType: "instance"` is unsupported because Yulin does not simulate EC2 instances. Omitting
+`TargetType` is also rejected because AWS would default it to `instance`.
 
 ## Listeners and the rules on them
 
-A listener answers on a port and holds the default actions for a request no rule claims. Rules carry
-a priority, and that is what decides which of several matching rules claims a request. Two rules on
-one listener cannot hold the same priority.
+A listener handles one port and provides the default action when no rule matches. When several
+rules match, the lowest priority number wins. Two rules on the same listener cannot use the same
+priority.
 
 ```typescript sim-elbv2-listener-rules
 /**
@@ -1761,7 +1751,7 @@ console.log(created.LoadBalancers?.[0]?.DNSName);
 // "shop-alb-0000000001.eu-west-2.elb.amazonaws.com"
 ```
 
-## Available functionality
+## Supported operations
 
 - `CreateLoadBalancer`, `DescribeLoadBalancers` and `DeleteLoadBalancer`, with a DNS name, ARN,
   canonical hosted zone id, scheme and state on every load balancer.

package/docs/services/eventbridge/README.md

@@ -1,12 +1,12 @@
 # Simulated EventBridge
 
-Yulin includes a simulated Amazon EventBridge for tests and local development. Event buses are held
-in memory and every operation is authorized by simulated IAM.
+Yulin simulates Amazon EventBridge event buses, rules, targets and `PutEvents` for tests and local
+development. Rules can match events, run on a simulated schedule, and deliver to simulated Lambda,
+SQS, SNS or ECS. Event buses and rules are stored in memory, and simulated IAM authorizes every
+operation.
 
-Event buses, rules, targets and `PutEvents`. A rule can send matched events to a simulated Lambda
-function, SQS queue or SNS topic, run a simulated ECS task, or fire on a schedule when a test
-advances simulated time. [EventBridge Scheduler](https://yulinsim.dev/services/scheduler/) is a separate service with its own
-docs. EventBridge-specific types are imported from the `@kensio/yulin/eventbridge` subpath.
+[EventBridge Scheduler](https://yulinsim.dev/services/scheduler/) is simulated separately. Import
+EventBridge-specific types from `@kensio/yulin/eventbridge`.
 
 ## Putting an event onto a bus
 
@@ -142,10 +142,8 @@ console.log(output.FailedEntryCount); // 0
 console.log(output.Entries?.[0]?.EventId !== undefined); // true
 ```
 
-This is real EventBridge behaviour, and not a gap here. AWS answers 200, finds no rule to match the
-event against, and drops it, without counting the entry as failed. A mistyped bus name therefore
-looks exactly like a working call. That is worth knowing before it costs an afternoon, and the
-simulation reproduces it faithfully.
+AWS also accepts and drops an event sent to a bus that does not exist. The entry is not counted as a
+failure, so check the bus name when `PutEvents` succeeds but no rule runs.
 
 ## Inspecting what a bus received
 
@@ -250,9 +248,8 @@ within the account. A rule ARN on the default bus is
 `arn:aws:events:<region>:<account>:rule/<name>`, and a rule on a custom bus carries the bus as well,
 as `rule/<bus>/<name>`.
 
-`PutRule` creates and updates alike, and an update **replaces** the rule rather than merging into
-it. A second request that leaves out the description clears the description. That is real behaviour
-and a common surprise.
+`PutRule` creates or updates a rule. An update replaces the stored rule instead of merging fields,
+so omitting the description clears it.
 
 `DisableRule` stops a rule matching, and `EnableRule` starts it again. A rule that was off picks up
 from the next event and leaves what it missed behind. `DeleteRule` on a rule that was never there
@@ -285,10 +282,9 @@ field, the pattern matches when the two lists overlap, and a pattern naming one
 event whose `resources` names several. `exists` is about the field and not its members, and a field
 carrying an empty list still exists.
 
-Anything else is refused at `PutRule`. The `cidr`, `equals-ignore-case`, `wildcard` and `$or`
-operators are all refused by name, as are the nested forms of `anything-but` and the
-case-insensitive forms of `prefix` and `suffix`. A pattern that silently matched nothing would look
-like a pattern that was simply too specific, and the rule would go unnoticed until the deployment.
+`PutRule` rejects unsupported operators instead of storing a pattern that can never match. These
+include `cidr`, `equals-ignore-case`, `wildcard`, `$or`, nested `anything-but`, and the
+case-insensitive forms of `prefix` and `suffix`.
 
 ## Testing a pattern without a rule
 
@@ -1049,7 +1045,7 @@ events across accounts that way, but nothing here can reach another simulation's
 treating a foreign ARN as local would let a test pass while the real call crossed a boundary it has
 no permission for.
 
-## Available functionality
+## Supported operations
 
 - `CreateEventBus`, `DeleteEventBus`, `DescribeEventBus`, `ListEventBuses` and `PutEvents`.
 - `PutRule`, `DeleteRule`, `DescribeRule`, `ListRules`, `EnableRule`, `DisableRule` and

package/docs/services/firehose/README.md

@@ -1,18 +1,16 @@
 # Simulated Kinesis Data Firehose
 
-Yulin includes a simulated Kinesis Data Firehose for tests and local development. A delivery stream
-takes records, buffers them, and writes them into a simulated S3 Bucket under the key format real
-Firehose uses. The records come from `PutRecord` or off a simulated Kinesis stream. A test can put an
-event and assert on the Object it landed in, without an AWS account and without waiting five minutes
-for a buffer to flush.
+Yulin simulates Kinesis Data Firehose delivery streams in memory. A stream accepts records directly
+or reads them from simulated Kinesis, buffers them, and writes each completed buffer to simulated S3.
+Advance simulated time to flush interval-based buffers without waiting in real time.
 
 Firehose specific types are imported from the `@kensio/yulin/firehose` subpath.
 
 ## Putting a record and finding the Object
 
-`simAws.firehose()` gives the service for the default account and region. A delivery stream needs a
-Bucket to write into and a Role to write as, so both exist before it does. Advancing the clock past
-the buffering interval is what delivers the buffer.
+`simAws.firehose()` returns Firehose for the default account and region. Create the destination
+bucket and delivery role before the delivery stream. Advance the clock past the buffering interval
+to write the buffered records.
 
 ```typescript sim-firehose-put-and-deliver
 /**
@@ -93,15 +91,13 @@ const { Contents } = await simAws
 console.log(Contents?.[0]?.Key);
 ```
 
-The put is answered straight away with a record id. The Bucket stays empty until the buffer is
-delivered. That delay is what a Firehose pipeline is built around.
+`PutRecord` returns a record ID immediately. The bucket remains empty until the buffer is delivered.
 
 ## Buffering
 
-A delivery stream holds its records until the buffer passes `SizeInMBs` or `IntervalInSeconds`,
-whichever comes first. Everything in one buffer arrives as one Object, with the records concatenated
-end to end. A producer that wants lines puts the newline on the end of each record. The example
-below does exactly that.
+A delivery stream flushes when it reaches `SizeInMBs` or `IntervalInSeconds`, whichever comes first.
+Firehose concatenates all records in the buffer into one S3 object. Add a newline to each record if
+the object should contain separate lines.
 
 `IntervalInSeconds` runs from the first record of a buffer. The default is 300 seconds and the
 default size is 5 MB, as they are on real Firehose.
@@ -224,8 +220,8 @@ the background scheduler, the way real Firehose answers the producer before it w
 
 ## The Object key
 
-The key is the `Prefix`, then the UTC date path, then the delivery stream name, its version, the
-delivery time and a random string:
+Object keys contain the configured `Prefix`, UTC date path, delivery stream name, version, delivery
+time, and a random suffix:
 
 ```
 <Prefix>YYYY/MM/DD/HH/<delivery-stream-name>-<version>-YYYY-MM-DD-HH-MM-SS-<random>
@@ -234,15 +230,15 @@ delivery time and a random string:
 A delivery stream with no `Prefix` gets the bare date path. The version is `1` and stays there,
 since a delivery stream's configuration is fixed once it is created.
 
-Simulated time is what the date path and the timestamp come from. A test that sets the clock to a
-known instant knows the prefix its Objects are under, and can list them.
+The date path and timestamp use simulated time. Set the clock before delivery to make the prefix
+predictable.
 
 ## Reading from a Kinesis stream
 
-A delivery stream can take its records off a simulated Kinesis stream instead. Create it with a
+A delivery stream can read records from simulated Kinesis. Create it with a
 `DeliveryStreamType` of `KinesisStreamAsSource` and a `KinesisStreamSourceConfiguration` naming the
-stream and the Role to read it as. Records put on the stream from then on are buffered and delivered
-the way put records are.
+stream and its read role. Records added after the delivery stream is created are buffered and sent
+to S3.
 
 ```typescript sim-firehose-kinesis-source
 /**
@@ -382,11 +378,8 @@ Creating a delivery stream hands Firehose the destination `RoleARN`, and the sou
 where it reads a Kinesis stream. `CreateDeliveryStream` authorizes `iam:PassRole` against each of
 them. See [passing a Role to a service](https://yulinsim.dev/services/iam/#passing-a-role-to-a-service) in the IAM docs.
 
-The delivery itself is a separate request, made as the delivery stream's `RoleARN`. The caller who
-put the record needs no S3 permission at all, and a Role that cannot write to the Bucket fails the
-delivery. Real
-Firehose answered that `PutRecord` minutes earlier, and what became of the buffer reaches the
-producer through CloudWatch. The simulator keeps the failure for a test to read instead.
+Delivery uses the delivery stream's `RoleARN`, not the identity that called `PutRecord`. The role
+needs `s3:PutObject` on the destination. Failed writes appear in `getDeliveryFailures()`.
 
 ```typescript sim-firehose-permissions
 /**
@@ -507,9 +500,8 @@ what a test checking the denial does. Anything else is also warned about on the
 `KinesisStreamSourceConfiguration` and `Tags` are read. A `Ref` gives the delivery stream name and
 `Fn::GetAtt` on `Arn` gives the ARN, the way real CloudFormation publishes them.
 
-A CDK `DeliveryStream` with an `S3Bucket` destination synthesizes that resource, along with the
-delivery Role and its policy. A CDK project reaches a simulated delivery stream by deploying its
-synthesized template, and nothing here has to be written by hand.
+A CDK `DeliveryStream` with an `S3Bucket` destination synthesizes this resource, its delivery role,
+and the role policy. Deploy that synthesized template directly into simulated CloudFormation.
 
 ```typescript sim-firehose-cloudformation
 /**
@@ -627,9 +619,9 @@ A `DeliveryStreamType` of `KinesisStreamAsSource` deploys as well. The
 `KinesisStreamSourceConfiguration` names the stream by ARN and the Role to read it as, and a stack
 declaring the stream beside the delivery stream archives what a producer puts on it.
 
-A delivery stream this simulation cannot deliver for is skipped and recorded in
-`stack.skippedResources`, and the rest of the stack deploys. That covers a destination other than
-S3, and a source property naming somewhere the records cannot come from, such as
+A delivery stream with an unsupported source or destination is recorded in
+`stack.skippedResources`, while the rest of the stack deploys. This includes destinations other than
+S3 and unsupported source properties such as
 `MSKSourceConfiguration` or `DatabaseSourceConfiguration`. The source property is what the skip is
 decided on, because a template that leaves `DeliveryStreamType` out gets `DirectPut` by default.
 

package/docs/services/glue/README.md

@@ -1,26 +1,17 @@
 # Simulated Glue
 
-Yulin includes a simulated Glue Data Catalog for tests and local development. It holds databases,
-tables and the partitions registered against them, deploys databases and tables from
-`AWS::Glue::Database` and `AWS::Glue::Table`, and hands them back through `GetDatabase` and
-`GetTable`. A test can assert that a stack declared the table definition it meant to, including the
-Athena partition projection its parameters configure.
+Yulin simulates Glue Data Catalog databases, tables and partitions. The catalog stores metadata. It
+does not read the data in S3.
 
-A table here is a definition. The data it describes stays in S3, unread, and the catalog answers
-with what it was told to hold.
-
-Simulated [Athena](https://yulinsim.dev/services/athena/ "Simulated Athena usage docs") reads this
-catalog. A query naming a table no database here holds fails the way real Athena fails it, and a
-table's partition projection is evaluated when a query runs against it. All four projection types
-are covered, `enum`, `integer`, `date` and `injected`. A projection with a mistake in its parameters
-fails the query that reads it.
+Simulated [Athena](https://yulinsim.dev/services/athena/ "Simulated Athena usage docs") reads the
+catalog and evaluates partition projection when it runs a query.
 
 Glue-specific types are imported from the `@kensio/yulin/glue` subpath.
 
 ## Deploying a database and a table
 
-A stack declares the database, and the table names it through `Ref`. Both read back through the SDK
-once the deploy finishes.
+Simulated CloudFormation deploys `AWS::Glue::Database` and `AWS::Glue::Table`. A table can name its
+database through `Ref`.
 
 ```typescript sim-glue-cloudformation
 /**
@@ -84,18 +75,15 @@ const { Table } = simAws
 console.log(Table.Parameters["projection.enabled"]);
 ```
 
-Partition projection lives entirely in `TableInput.Parameters`. Those parameters are read into the
-table, and never recorded as ignored. A table whose parameters were dropped on the way in deploys
-green while projecting none of them. Simulated Athena reads those same parameters when a query runs.
-A broken projection fails that query.
+Partition projection configuration is stored in `TableInput.Parameters`. Athena reads these
+parameters when a query runs and rejects invalid projection configuration.
 
 `Ref` answers with the database name and with the table name.
 
 ## Names are folded to lower case
 
-A database name and a table name are both folded to lower case when they are stored. Real Glue folds
-them the same way, for compatibility with Apache Hive. A database created as `Rainlytics` is stored,
-reported and queried as `rainlytics`.
+Database and table names are stored in lower case. A database created as `Rainlytics` is reported as
+`rainlytics`.
 
 ```typescript sim-glue-name-folding
 /**
@@ -123,36 +111,27 @@ const { Database } = glue.getDatabase(
 console.log(Database.Name);
 ```
 
-Two names differing only by case are one name. A second `CreateDatabase` for `Rainlytics` after one
-for `rainlytics` is an `AlreadyExistsException`, and a `GetTable` finds the table under whichever
-spelling it is asked for.
+Names that differ only by case refer to the same database or table. Creating the second one raises
+`AlreadyExistsException`.
 
-Column names keep the case they were given, including partition keys. Real Glue leaves those alone,
-and simulated [Athena](https://yulinsim.dev/services/athena/ "Simulated Athena usage docs") folds a
-column name only when it runs a query.
+Column and partition key names keep their original case.
 
-A database or a table the template leaves unnamed is named from the stack name, the logical ID and a
-tail derived from both, folded the same way. A `LogTable` in `analytics-stack` becomes
-`analytics-stack-logtable-` and twelve more characters, where real CloudFormation ends the name in
-twelve random ones. The name is trimmed to the 255 bytes the catalog allows, and [the CloudFormation docs](https://yulinsim.dev/services/cloudformation/#names-cloudformation-generates "Names CloudFormation generates")
-cover how the stack name and the logical ID share what is left.
+CloudFormation generates a lower-case name when the template omits one. See
+[generated resource names](https://yulinsim.dev/services/cloudformation/#names-cloudformation-generates "Names CloudFormation generates").
 
 ## Reading the catalog back
 
-`GetDatabase`, `GetDatabases`, `GetTable` and `GetTables` answer through the SDK. A `SimGlue` also
-carries `findDatabase`, `findTable`, `allDatabases`, `tablesInDatabase`, `findPartition` and
-`partitionsInTable`. Those read the same state without going through a Command or its
-authorization.
+Use the SDK commands to read the catalog through IAM authorization. The `findDatabase`, `findTable`,
+`allDatabases`, `tablesInDatabase`, `findPartition` and `partitionsInTable` accessors read the same
+state directly.
 
-The storage descriptor keeps its columns in the order they were declared, and the partition keys
-keep theirs. The two stay apart, the way real Glue keeps them. A partition key repeated among the
-storage descriptor's columns gives a table Athena refuses to query.
+Storage descriptor columns and partition keys keep their declared order. Athena rejects a table
+that repeats a partition key in the storage descriptor columns.
 
 ## Registering partitions
 
-A crawler, `MSCK REPAIR TABLE` or `ALTER TABLE ADD PARTITION` fills a real catalog's partition list.
-Here the six partition commands do it. A partition is keyed by its values in the order the table's
-`PartitionKeys` declares them, and carries a storage descriptor saying where its own data sits.
+Register partitions with the Glue partition commands. Values follow the order of the table's
+`PartitionKeys`. Each partition may provide its own storage descriptor.
 
 ```typescript sim-glue-partitions
 /**
@@ -219,24 +198,19 @@ console.log(Errors.length);
 console.log(Partitions[1]?.StorageDescriptor?.Location);
 ```
 
-`CreatePartition` registers one partition and `BatchCreatePartition` registers a list of them.
-`GetPartition` reads one back by its values, and `GetPartitions` answers with a table's partitions in
-registration order. `DeletePartition` and `BatchDeletePartition` remove them.
+`CreatePartition` and `BatchCreatePartition` register partitions. `GetPartition` reads one by its
+values. `GetPartitions` returns them in registration order. The delete commands remove them.
 
-A batch reports what it could not do in `Errors` and carries on with the rest, the way real Glue
-does. Each entry there carries the values it was given and an `ErrorCode` naming the refusal, so a
-job re-run over a week of days learns which days were already registered and registers the others.
+A batch continues after an individual partition fails. Its `Errors` list contains the supplied
+values and an `ErrorCode` for each failure.
 
-Values are positional. A `Values` list of a different length from the table's `PartitionKeys` lines
-up with the wrong keys, and is refused with `InvalidInputException` naming both counts. Registering
-one day twice is an `AlreadyExistsException`, since registration is not idempotent on real Glue.
-Deleting a table removes the partitions registered against it, the way deleting a database removes
-its tables.
+The number of values must match the number of partition keys. A mismatch raises
+`InvalidInputException`. Registering the same values twice raises `AlreadyExistsException`. Deleting
+a table removes its partitions, and deleting a database removes its tables.
 
 ## Filtering partitions
 
-`GetPartitions` takes an `Expression` and answers with the partitions it matches. A request carrying
-none reads them all.
+Pass `Expression` to `GetPartitions` to filter the result. Omitting it returns every partition.
 
 ```typescript sim-glue-partition-expressions
 /**
@@ -295,28 +269,19 @@ const { Partitions } = glue.getPartitions(
 console.log(JSON.stringify(Partitions.map((partition) => partition.Values)));
 ```
 
-A term names a partition key, an operator, and whatever the operator takes. The operators are `=`,
-`<>` and `!=`, `>`, `<`, `>=`, `<=`, `LIKE`, `IN` and `BETWEEN`, and `BETWEEN` takes both of its
-ends. `AND`, `OR` and `NOT` combine terms and brackets group them, with the precedence SQL gives
-them (`NOT` binds tightest, then `AND`, then `OR`). `NOT` also sits in front of `LIKE`, `IN` and
-`BETWEEN` to reverse that one term.
+Expressions support `=`, `<>`, `!=`, `>`, `<`, `>=`, `<=`, `LIKE`, `IN` and `BETWEEN`. Combine terms
+with `AND`, `OR`, `NOT` and parentheses. Operator precedence is `NOT`, then `AND`, then `OR`.
 
-Comparison follows the type the table declares for the key. `tinyint`, `smallint`, `int`, `integer`,
-`bigint`, `float`, `double` and `decimal` compare as numbers, so `10` sorts above `9` rather than
-below it. Every other declared type compares as text, which is the order a date written the ISO way
-already has. A key declared as a number is held to a numeric literal, and `hour = 'noon'` is refused
-rather than matching nothing.
+Numeric partition key types use numeric comparison. Other types use text comparison. A numeric key
+requires a numeric literal.
 
-`LIKE` matches the value's text whatever type the key is declared with, since that is what `LIKE`
-does. `%` stands for any run of characters and `_` for exactly one.
+`LIKE` treats the value as text. `%` matches any sequence and `_` matches one character.
 
-An expression naming a column the table does not partition by is refused, naming the column and the
-keys the table does have. So is one that cannot be read, and the message says where reading stopped.
+An unknown partition key or invalid expression is rejected with a position-aware error.
 
 ## Intercepting a GlueClient
 
-An intercepted `GlueClient` reaches the simulated catalog, so code under test builds its own client
-and sends its own Commands.
+Intercept a `GlueClient` when application code constructs the client itself.
 
 ```typescript sim-glue-sdk-interception
 /**
@@ -357,11 +322,9 @@ console.log(TableList?.[0]?.Name);
 
 ## Permissions
 
-Every Command authorizes through simulated IAM. Data Catalog resources are a hierarchy with the
-catalog at the root, and an operation on one needs permission on that resource and on every ancestor
-of it. Reading a table needs the table, the database and the catalog, and a policy naming only the
-table ARN is denied. Deleting a database needs permission on every table in it as well, since the
-tables go with it.
+Every command uses simulated IAM. Catalog resources form a hierarchy. A table operation needs
+permission on the table, database and catalog. Deleting a database also needs permission on its
+tables.
 
 ```typescript sim-glue-permissions
 /**
@@ -441,7 +404,7 @@ const { Table } = glue.getTable(
 console.log(Table.Name);
 ```
 
-A policy listing only the table ARN is refused here, and refused by real Glue for the same reason.
+A policy that grants only the table ARN is insufficient.
 
 ## Available functionality