@kensio/yulin 1.21.6 → 1.21.8

package/docs/services/ses/README.md

@@ -1,20 +1,14 @@
 # Simulated SES
 
-Yulin includes a simulated Amazon SES for tests and local development, through the SES v2 API. It
-holds email identities, applies the sandbox rules, and keeps a record of every message it would have
-sent. A test can assert that signing someone up produced a welcome email addressed to them, without
-an AWS account and without a mailbox to read.
-
-There is no delivery to simulate. A message SES accepts leaves AWS for a mail system. The whole of
-the observable AWS behaviour is whether SES would have accepted the message and what it would have
-sent. That is what makes this service small and what makes it useful.
+Yulin simulates the Amazon SES v2 API in memory. It stores email identities, applies sandbox and
+suppression rules, renders templates, and records accepted messages. It does not deliver email.
 
 SES specific types are imported from the `@kensio/yulin/ses` subpath.
 
 ## Asserting on a message that was sent
 
-`sentEmails()` hands over the record. Each message carries who it was from, the three recipient
-lists, the subject, the body, its attachments and the message id SES answered with.
+Use `sentEmails()` to inspect accepted messages. Each record contains the sender, To/Cc/Bcc lists,
+subject, body, attachments, and message ID.
 
 ```typescript sim-ses-send-and-assert
 /**
@@ -115,9 +109,8 @@ console.log(
 
 ## Verifying identities
 
-Real SES verifies an email address by emailing it a link and a domain by looking for DNS records.
-Neither can happen inside a test process, so verification here is the simulator's own operation
-instead of an API call. `verifyIdentity` performs it, creating the identity where one is absent.
+SES normally verifies an address by email and a domain through DNS. In tests, call `verifyIdentity`
+instead. It creates the identity if necessary and marks it verified.
 
 Everything else about identities is the ordinary SES API. `CreateEmailIdentity` starts one, and it
 starts unverified, exactly as a real one does:
@@ -631,13 +624,10 @@ one answer whoever asked.
 
 ## The sandbox
 
-An account starts in the SES sandbox, where **both** the sender and every recipient have to be
-verified. That is the state most tests should be written against. It is the configuration that
-refuses to mail an address nobody verified, and catching that refusal in a test is much better than
-catching it in an account.
+An account starts in the SES sandbox. Both the sender and every recipient must be verified. Outside
+the sandbox, only the sender must be verified.
 
-Outside the sandbox only the sender is checked. `PutAccountDetails` with `ProductionAccessEnabled`
-is how an account gets there:
+Call `PutAccountDetails` with `ProductionAccessEnabled` to leave the sandbox:
 
 ```typescript sim-ses-sandbox
 /**
@@ -696,17 +686,12 @@ caller finds out everything it has to verify from one failure:
 Email address is not verified. The following identities failed the check in region US-EAST-1: someone@example.org
 ```
 
-Real SES treats `ProductionAccessEnabled` as a request that a human at AWS then reviews, and an
-account stays in the sandbox until that review lands. Granting it immediately is a deliberate
-divergence. The alternative is a simulator no test can get out of the sandbox in, and waiting for a
-review is beyond what a test can assert on anyway.
+Unlike AWS, Yulin grants production access immediately instead of waiting for a manual review.
 
 ## The suppression list
 
-Real SES holds an account-level suppression list and fills it from hard bounces and complaints.
-Tests supply that feedback explicitly with `recordFeedback`. Suppression commands manage the same
-list. The support tool that lists suppressed addresses, the form that removes one and the script
-that seeds the list all have somewhere to run.
+SES maintains an account suppression list for hard bounces and complaints. Tests add feedback with
+`recordFeedback`, and the suppression commands read and change the same list.
 
 `PutSuppressedDestination`, `GetSuppressedDestination`, `ListSuppressedDestinations` and
 `DeleteSuppressedDestination` manage it.
@@ -870,8 +855,7 @@ recorded.
 
 ## Messages on the console
 
-`sentEmails()` is test code. A dev server has the same messages going past and nothing to read them
-with, so `serveSimAws` prints a summary of each one as SES accepts it:
+For local development, `serveSimAws` prints a summary whenever SES accepts a message:
 
 ```
 sim SES: hello@example.com to alice@example.com, bcc audit@example.com
@@ -899,13 +883,12 @@ pool kept. Both services recorded it, and each block says what that service hold
 
 ## Permissions
 
-Every command authorizes through simulated IAM. A send authorizes against the identity being sent
-**from**, and recipients never enter into it. That is worth knowing when a policy looks like it
-should cover a send and fails to.
+Every command uses simulated IAM. A send authorizes against the sender identity, not the recipient
+addresses.
 
 ```typescript sim-ses-permissions
 /**
- * A Role that may only send from one domain.
+ * A Role that may only send from one address at a verified domain.
  */
 
 import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
@@ -945,6 +928,9 @@ await simAws.iam().putRolePolicy(
           Effect: "Allow",
           Action: "ses:SendEmail",
           Resource: "arn:aws:ses:us-east-1:111111111111:identity/example.com",
+          Condition: {
+            StringEquals: { "ses:FromAddress": "hello@example.com" },
+          },
         },
       ],
     }),
@@ -953,7 +939,7 @@ await simAws.iam().putRolePolicy(
 
 await ses.sendEmail(
   new SendEmailCommand({
-    FromEmailAddress: "anything@example.com",
+    FromEmailAddress: "hello@example.com",
     Destination: { ToAddresses: ["someone@example.com"] },
     Content: {
       Simple: {
@@ -978,6 +964,10 @@ The more specific identity wins when both exist. A policy naming `identity/examp
 send from any address at the domain, unless that address is an identity in its own right, in which
 case the send authorizes against `identity/hello@example.com` instead.
 
+`ses:FromAddress` carries the bare `FromEmailAddress`. A policy can use it to allow one address at a
+verified domain. A display name does not change the value. For example, `Welcome team
+<hello@example.com>` supplies `hello@example.com` to IAM.
+
 `ses:ListEmailIdentities`, `ses:GetAccount` and `ses:PutAccountDetails` have no resource type at all
 on real SES, and only a policy written against `*` allows them. A policy scoped to identity ARNs
 allows none of the three. Not even one written against `identity/*`, the intuitive reading and the

package/docs/services/sns/README.md

@@ -1,14 +1,11 @@
 # Simulated SNS
 
-Yulin includes a simulated Amazon SNS for tests and local development. Topics are held in memory and
-every operation is authorized by simulated IAM.
+Yulin simulates Amazon SNS standard topics for tests and local development. A published message can
+reach simulated SQS queues, invoke simulated Lambda functions or create SMS records that tests can
+inspect. Direct SMS publishes are recorded in the same way.
 
-Standard topics only. SNS-specific types are imported from the `@kensio/yulin/sns` subpath.
-
-A message published to a topic is delivered to every queue subscribed to it, invokes every Lambda
-function subscribed to it, and is recorded as an SMS for every phone number subscribed to it. Only
-those three protocols are simulated. A message published straight to a phone number is recorded
-as an SMS a test can assert on.
+Topics are stored in memory, and simulated IAM authorizes every operation. FIFO topics and other
+subscription protocols are not simulated. Import SNS-specific types from `@kensio/yulin/sns`.
 
 ## Creating a topic and publishing to it
 
@@ -103,11 +100,10 @@ console.log(read.Attributes?.["SubscriptionsConfirmed"]); // "0"
 reports it. The three subscription counts are reported as zero, the counts a topic with no
 subscriptions has.
 
-An attribute real SNS has and this simulation gives no behaviour to is refused by name rather than
-taken and ignored. That covers `FifoTopic`, `KmsMasterKeyId`, `SignatureVersion`, `TracingConfig`,
-`ArchivePolicy`, `DeliveryPolicy`, `ContentBasedDeduplication` and the delivery status logging
-attributes such as `SQSSuccessFeedbackRoleArn`. A topic that appeared to accept `KmsMasterKeyId`
-would look encrypted to the request that set it and be plain to everything else.
+Unsupported topic attributes are rejected instead of being stored without effect. These include
+`FifoTopic`, `KmsMasterKeyId`, `SignatureVersion`, `TracingConfig`, `ArchivePolicy`, `DeliveryPolicy`,
+`ContentBasedDeduplication` and delivery status logging attributes such as
+`SQSSuccessFeedbackRoleArn`.
 
 ## Publishing
 
@@ -148,12 +144,11 @@ const published = await sns.publish(
 console.log(published.MessageId !== undefined); // true
 ```
 
-The name and data type rules are the real ones. A data type is `String`, `String.Array`, `Number` or
-`Binary`, and each takes a custom label after a dot, so `Number.int` is a number as far as the rules
-go. A reserved `AWS.` or `Amazon.` prefix on a name, a data type built on none of the four, or a
-value that disagrees with its data type is refused. A test finds any of those without going near AWS. The two reserved names real
-SNS defines for SMS, `AWS.SNS.SMS.SenderID` and `AWS.SNS.SMS.SMSType`, are the exception.
-[Sending an SMS](#sending-an-sms) covers those.
+Message attributes use the AWS name and type rules. A type starts with `String`, `String.Array`,
+`Number` or `Binary` and may add a custom label after a dot, such as `Number.int`. SNS rejects
+reserved `AWS.` and `Amazon.` name prefixes, unknown base types and values that do not match their
+type. The SMS attributes `AWS.SNS.SMS.SenderID` and `AWS.SNS.SMS.SMSType` are exceptions. See
+[Sending an SMS](#sending-an-sms).
 
 A `Subject` is UTF-8 text with no line breaks or control characters, of fewer than 100 characters.
 That is the contract real SNS states. A subject of exactly 100 characters is already too long. A
@@ -164,9 +159,8 @@ publish with no `Message`, or with one over the size limit, is refused with
 the rest of the batch goes through, as real SNS reports it. An empty batch, more than ten entries, a
 malformed entry id or two entries sharing an id fail the whole request.
 
-The size limit is the one thing a batch is held to as a whole. Ten entries each just inside it are
-one batch far outside it, and a single entry over it fails the whole batch with
-`BatchRequestTooLongException`. The response singles out no entry.
+The size limit applies to the whole batch. A batch over the limit fails with
+`BatchRequestTooLongException`, without identifying one entry as the cause.
 
 ```typescript sim-sns-publish-batch
 /**
@@ -1742,24 +1736,29 @@ ARNs, and `Ref` on an `AWS::SNS::Topic` gives one.
 
 A property with no simulated behaviour fails the resource rather than being dropped. That covers
 `FifoTopic`, `ContentBasedDeduplication`, `FifoThroughputScope`, `KmsMasterKeyId`,
-`SignatureVersion`, `TracingConfig`, `ArchivePolicy`, `DeliveryStatusLogging`, `DataProtectionPolicy`
-and `Tags` on a topic, and `DeliveryPolicy`, `RedrivePolicy`, `ReplayPolicy`, `SubscriptionRoleArn`
-and `Region` on a subscription. Most of them are refused by simulated SNS itself, since they are
-topic or subscription attributes of the same name, and the reason is the same one an SDK caller gets.
-A property the resource type never had is refused too. The failure is worded as an invalid resource,
-which fails the resource where an unsupported one would be
+`SignatureVersion`, `TracingConfig`, `ArchivePolicy`, `DeliveryStatusLogging` and
+`DataProtectionPolicy` on a topic, and `DeliveryPolicy`, `RedrivePolicy`, `ReplayPolicy`,
+`SubscriptionRoleArn` and `Region` on a subscription. Most of them are refused by simulated SNS
+itself, since they are topic or subscription attributes of the same name, and the reason is the same
+one an SDK caller gets. A property the resource type never had is refused too. The failure is worded
+as an invalid resource, which fails the resource where an unsupported one would be
 [skipped](https://yulinsim.dev/services/cloudformation/#values-from-a-skipped-resource). A topic that cannot be created
 as the template asked for it would otherwise leave a stack that looks deployed with no publisher
 behind it.
 
+`Tags` is the one difference from `CreateTopic`, which refuses it outright. A template's tags are
+usually the whole stack's (a CDK app calling `Tags.of(app).add(...)` tags every topic in it), and a
+topic delivers the same messages whether it carries them or not. They are recorded as an ignored
+property and the deploy stands. Nothing reads them back either.
+
 CDK works without hand-editing. `topic.addSubscription(new subscriptions.SqsSubscription(queue))`
 synthesises an `AWS::SNS::Subscription` alongside the `AWS::SQS::QueuePolicy` that authorizes the
 delivery, and both deploy. `new subscriptions.LambdaSubscription(fn)` does the same with the
 `AWS::Lambda::Permission` beside it.
 
-## Available functionality
+## Supported operations
 
-Sim SNS currently supports:
+Simulated SNS supports:
 
 - `CreateTopicCommand`, idempotent for a name already taken, and `DeleteTopicCommand`
 - `ListTopicsCommand`, paged at a hundred topics with a `NextToken`
@@ -1802,8 +1801,6 @@ Sim SNS currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - Only the `sqs`, `lambda` and `sms` subscription protocols are simulated. A queue, a function and a
   phone number are the only things a topic can deliver to. `http`, `https`, `email`, `email-json`,
   `application` and `firehose` are refused at `Subscribe` time.
@@ -1880,7 +1877,8 @@ Current documented limitations:
 - Encryption is left out. `KmsMasterKeyId` is refused, and message bodies are held in process memory
   as they were published. Anything sharing the process can read them.
 - Tags are left out. `TagResource`, `UntagResource` and `ListTagsForResource` are absent, and
-  `CreateTopic` refuses a `Tags` parameter rather than dropping it.
+  `CreateTopic` refuses a `Tags` parameter rather than dropping it. An `AWS::SNS::Topic` carrying
+  `Tags` deploys with the tags dropped and the property recorded.
 - Data protection policies are left out. `PutDataProtectionPolicy` and `GetDataProtectionPolicy` are
   absent, and `CreateTopic` refuses a `DataProtectionPolicy` rather than creating a topic that
   redacts nothing.

package/docs/services/sqs/README.md

@@ -1,9 +1,11 @@
 # Simulated SQS
 
-Yulin includes a simulated Amazon SQS for tests and local development. Messages are held in memory,
-hidden and released on the simulation's own clock, and every operation is authorized by simulated IAM.
+Yulin simulates Amazon SQS standard queues for tests and local development. You can create queues,
+send and receive messages, test visibility timeouts and redrive messages to dead-letter queues.
+Messages are stored in memory, time-based behavior uses the simulation's clock, and simulated IAM
+authorizes every operation.
 
-Standard queues only. SQS-specific types are imported from the `@kensio/yulin/sqs` subpath.
+FIFO queues are not simulated. Import SQS-specific types from `@kensio/yulin/sqs`.
 
 ## Creating a queue and sending a message
 
@@ -57,10 +59,9 @@ differ. A request naming no attributes always matches.
 
 ## Visibility timeouts
 
-A received message is hidden from other consumers for the queue's visibility timeout, 30 seconds by
-default. The message records the instant it is hidden until. It becomes receivable again once
-simulated time reaches that instant. Advancing the clock is all a test needs to watch an undeleted
-message come back.
+A received message is hidden from other consumers for the queue's visibility timeout, which is 30
+seconds by default. If the consumer does not delete it, the message becomes available again when the
+simulated clock reaches the end of that timeout.
 
 ```typescript sim-sqs-visibility-timeout
 /**
@@ -127,8 +128,8 @@ Every receive issues a fresh receipt handle, and a delete has to use the handle
 receive of that message. A handle from an earlier receive is accepted and deletes nothing. Real SQS
 accepts one too, and promises only that the message might not be deleted.
 
-That is the failure a consumer slower than its visibility timeout hits. Its message went back on the
-queue, someone else took it, and its own delete quietly does nothing.
+This can happen when a consumer runs past the visibility timeout and another consumer receives the
+same message. The first consumer's later delete succeeds without deleting the message.
 
 ```typescript sim-sqs-stale-receipt-handle
 /**
@@ -187,10 +188,9 @@ still the most recent one, so deleting with it works. A handle the queue never i
 
 ## Dead-letter queues
 
-A `RedrivePolicy` says where a message goes once a consumer has had enough attempts at it. Once a
-message has been received `maxReceiveCount` times without being deleted, the next lapse of its
-visibility timeout moves it to the queue named by `deadLetterTargetArn`. Advancing the clock drives
-the move, as it drives the timeout itself.
+A `RedrivePolicy` sends repeatedly received messages to a dead-letter queue. After a message reaches
+`maxReceiveCount` without being deleted, the next visibility timeout moves it to the queue named by
+`deadLetterTargetArn`. Advance the simulated clock to trigger the timeout and move.
 
 ```typescript sim-sqs-dead-letter-queue
 /**
@@ -1137,7 +1137,7 @@ that deploys here, with the queue URL reaching the function through its environm
 policy naming the queue by the ARN `Fn::GetAtt` gives. A grant to a service principal synthesises an
 `AWS::SQS::QueuePolicy` alongside it, which deploys too.
 
-## Available functionality
+## Supported operations
 
 Sim SQS currently supports:
 

package/docs/services/ssm/README.md

@@ -1,12 +1,11 @@
 # Simulated SSM Parameter Store
 
-Yulin includes a simulated AWS Systems Manager Parameter Store for tests and local development.
-Parameters are stored in memory, versioned on every write, and every operation is authorized by
-simulated IAM.
+Yulin simulates AWS Systems Manager Parameter Store for tests and local development. You can create,
+read, update and delete parameters through the AWS SDK or a CloudFormation template. Parameters are
+stored in memory, each write creates a version, and simulated IAM authorizes every operation.
 
-Only Parameter Store is simulated.
-
-SSM-specific types are imported from the `@kensio/yulin/ssm` subpath.
+Other Systems Manager features, such as Run Command and Session Manager, are not simulated. Import
+SSM-specific types from `@kensio/yulin/ssm`.
 
 ## Writing and reading a parameter
 
@@ -292,8 +291,7 @@ console.log(origins.length); // 2
 
 ## Parameter names
 
-Name validation matches real Parameter Store, because a name it accepts and AWS refuses is a
-deployment failure a passing test would have hidden. A name:
+Parameter names use the same validation rules as AWS. A name:
 
 - may contain letters, digits, `_`, `.`, `-` and `/`
 - must start with `/` if it contains a hierarchy at all
@@ -302,8 +300,8 @@ deployment failure a passing test would have hidden. A name:
 - may not contain spaces between characters, though surrounding spaces are stripped
 - may not make an ARN longer than 1011 characters, counting the ARN prefix for the account and region
 
-A `String` or `StringList` value holds at most 4KB, the standard tier limit. This is the one people
-hit, usually by putting a whole JSON configuration blob in one parameter.
+A `String` or `StringList` value holds at most 4 KB, the standard tier limit. Larger configuration
+documents must be split across parameters or stored elsewhere.
 
 ## Deploying a parameter from CloudFormation
 
@@ -455,9 +453,9 @@ covers that one.
 
 ### A reference the simulation cannot answer
 
-Simulated CloudFormation deploys what it can. A reference naming a parameter that was never created
-resolves to `dummy-value-for-<name>`, and the stack carries on deploying. A template reading
-configuration a test does not care about is still worth deploying for everything else in it.
+When a reference names a parameter that does not exist, simulated CloudFormation substitutes
+`dummy-value-for-<name>` and continues the deployment. This lets a test deploy the rest of a
+template without setting up unrelated configuration.
 
 The substitution is recorded on
 [`stack.ignoredProperties`](https://yulinsim.dev/services/cloudformation/#properties-a-resource-was-created-without),
@@ -998,9 +996,9 @@ console.log(read.Parameter?.Value); // "hunter2"
 
 `DescribeParameters` reports the key each `SecureString` is encrypted under as `KeyId`.
 
-## Available functionality
+## Supported operations
 
-Sim SSM currently supports:
+Simulated Parameter Store supports:
 
 - `PutParameterCommand`, creating a parameter or overwriting one
 - `GetParameterCommand`, by name, by `name:version` or by `name:label`
@@ -1026,8 +1024,6 @@ Sim SSM currently supports:
 
 ## Limitations
 
-Current documented limitations:
-
 - Only standard tier `SecureString` encryption is simulated, which encrypts under the KMS key
   directly. The advanced tier's envelope encryption through the AWS Encryption SDK is left out, and
   `kms:GenerateDataKey` is never needed.
@@ -1039,7 +1035,8 @@ Current documented limitations:
 - Parameter policies (expiration and notification) are left out. `Policies` is refused, and
   `DescribeParameters` always reports an empty `Policies` list.
 - Tags are left out. `Tags` on `PutParameter` is refused, and `AddTagsToResource`,
-  `RemoveTagsFromResource` and `ListTagsForResource` are absent.
+  `RemoveTagsFromResource` and `ListTagsForResource` are absent. An `AWS::SSM::Parameter` carrying
+  `Tags` deploys with the tags dropped and the property recorded.
 - `AllowedPattern` is refused outright. Ignoring it would store a value it was meant to reject,
   without complaint.
 - `KeyId` on a `String` or `StringList` parameter is refused, since nothing would encrypt a value
@@ -1060,9 +1057,10 @@ Current documented limitations:
 - Deletion is immediate. Real Parameter Store asks for thirty seconds before a deleted name is
   reused, where here the name is free straight away.
 - `AWS::SSM::Parameter` supports `Name`, `Type`, `Value`, `Description` and `Tier`. `AllowedPattern`,
-  `DataType`, `Policies` and `Tags` reach `PutParameter`, which refuses them for the reasons above.
-  `Type: SecureString` is refused, as real CloudFormation refuses it for this resource type. The
-  plaintext value would sit in the template.
+  `DataType` and `Policies` reach `PutParameter`, which refuses them for the reasons above. `Tags`
+  is the one difference from the command, and is recorded as an ignored property so a stack that
+  tags every Resource in it still deploys. `Type: SecureString` is refused, as real CloudFormation
+  refuses it for this resource type. The plaintext value would sit in the template.
 - The other `AWS::SSM::*` resource types (`Document`, `Association`, `MaintenanceWindow`,
   `PatchBaseline`, `ResourceDataSync` and the rest) are reported as unsupported and skipped.
 - Every deployment of an `AWS::SSM::Parameter` is a create. A name another stack already used is

package/docs/services/stepfunctions/README.md

@@ -1,18 +1,18 @@
 # Simulated Step Functions
 
-Simulated Step Functions interprets Amazon States Language and runs a state machine in the same
-process as the code under test. A workflow held in a template as data becomes something a test can
-run and assert on.
+Yulin interprets Amazon States Language and runs Step Functions state machines in the same process
+as the code under test. Tests can start executions, invoke simulated services, advance waits and
+inspect execution history without deploying a workflow.
 
-Types for simulated Step Functions are imported from the `@kensio/yulin/stepfunctions` subpath.
+Import Step Functions-specific types from `@kensio/yulin/stepfunctions`.
 
-## What runs today
+## Supported state machine features
 
-Every state type Amazon States Language defines runs. `Pass`, `Task`, `Succeed`, `Fail`, `Choice`,
-`Wait`, `Parallel` and `Map`.
+All eight state types are supported: `Pass`, `Task`, `Succeed`, `Fail`, `Choice`, `Wait`, `Parallel`
+and `Map`.
 
-The data-flow fields run in full. `InputPath`, `Parameters`, `ResultSelector`, `ResultPath` and
-`OutputPath` apply in that order, reading Reference Paths and the intrinsic functions.
+The data-flow fields `InputPath`, `Parameters`, `ResultSelector`, `ResultPath` and `OutputPath` run in
+that order. They support Reference Paths and intrinsic functions.
 
 A `Task` state invokes a simulated Lambda function, calls an operation on any other simulated
 service, or starts another state machine. A `Resource` this simulator has no answer for is refused
@@ -114,23 +114,21 @@ console.log(described.status); // FAILED
 console.log(described.error); // NotEligible
 ```
 
-A failing execution is recorded on the execution, and the call returns as it would for one that
-succeeded. Simulated EventBridge treats an undeliverable event the same way. An execution failing is
-as often the thing under test as it is a fault, and raising it would fail an unrelated `advanceBy`
-elsewhere in the same test.
+A failed execution records its status and error instead of throwing from `StartExecution`. Read it
+with `DescribeExecution` or the inspection API. This keeps workflow failure available for
+assertions.
 
 ## Invoking a Lambda function
 
 A `Task` state invokes a simulated Lambda function, through either of the two `Resource` forms CDK's
 `LambdaInvoke` emits.
 
-`arn:aws:states:::lambda:invoke` is the integration Step Functions optimises. The state is talking to
-the Lambda API, so its `Parameters` are an `Invoke` request (`FunctionName` names the function and
-`Payload` carries what it is sent) and its result is an `Invoke` response, with the handler's answer
-under `Payload`.
+With `arn:aws:states:::lambda:invoke`, `Parameters` has the shape of a Lambda `Invoke` request.
+`FunctionName` selects the function, `Payload` contains its input, and the handler result appears
+under `Payload` in the task output.
 
-A function ARN sends the state's own input to the handler and answers with what the handler
-returned. CDK writes this form for `payloadResponseOnly`.
+A function ARN sends the state input directly to the handler and uses the handler result as the task
+output. CDK emits this form when `payloadResponseOnly` is enabled.
 
 ```typescript sim-step-functions-task
 /**
@@ -1334,7 +1332,7 @@ reference contradicts itself here, listing a differing role ARN under `StateMach
 while the operation's own note says the difference is ignored. The note is the more specific of the
 two and is what this follows.
 
-## Still to come
+## Limitations
 
 - Distributed Map, with `ItemReader`, `ResultWriter` and the `ToleratedFailure` fields.
 - The `.sync` pattern, task tokens and activities.

package/docs/services/sts/README.md

@@ -1,16 +1,12 @@
 # Simulated STS
 
-Yulin includes a simulated STS (Security Token Service) for tests and local development.
-
-Sim STS is used through `SimAws` as `simAws.sts()`, scoped to the Account making the assume request.
-It simulates assuming IAM Roles. An assume request is evaluated against
-[simulated IAM](https://yulinsim.dev/services/iam/) policies, and a request that passes issues temporary session credentials
-that the rest of the simulated environment authenticates like real AWS credentials.
+Yulin simulates `AssumeRole` and `GetCallerIdentity`. Access the service through `simAws.sts()` or an
+intercepted `STSClient`.
 
 ## Basic usage
 
-Create a Role whose trust policy allows the Account to assume it, then assume it through STS. An
-omitted caller defaults to the Account root principal.
+Create a role with a trust policy, then call `assumeRole`. A request with no caller runs as the
+account root.
 
 ```typescript sim-sts-assume-role
 /**
@@ -50,23 +46,28 @@ console.log(assumeRoleOutput.Credentials?.AccessKeyId);
 console.log(assumeRoleOutput.Credentials?.Expiration);
 ```
 
-The output matches the AWS shape. `AssumedRoleUser.Arn` is the session ARN, such as
+`AssumedRoleUser.Arn` is the session ARN, such as
 `arn:aws:sts::123456789012:assumed-role/TargetRole/test-session`, and `Credentials` carries the
 temporary `AccessKeyId`, `SecretAccessKey`, `SessionToken`, and `Expiration`.
 
-The issued credentials are registered with the target Account's sim IAM. They authenticate later
-simulated requests, for example as the `caller` of an IAM authorization attempt, where identity
-policies come from the underlying Role. See [the sim IAM docs](https://yulinsim.dev/services/iam/#sts-assumerole-sessions) for a
-full example. Credentials missing their session token, or used after `Expiration`, are rejected with
-an AWS-like invalid-credentials error.
+Yulin registers the credentials with simulated IAM in the target account. Later requests use the
+role's identity policies. See [STS sessions in simulated IAM](https://yulinsim.dev/services/iam/#sts-assumerole-sessions).
+Credentials fail after `Expiration` or when the session token is missing.
+
+`DurationSeconds` defaults to 3,600 seconds and must be a positive integer.
+
+## Reading the current identity
 
-`DurationSeconds` controls the session lifetime and defaults to 3600 seconds (one hour). It must be
-a positive integer.
+`getCallerIdentity` reports the caller's ARN, account ID and user ID. It handles account roots, IAM
+users and assumed-role sessions. The intercepted and served STS APIs also support
+`GetCallerIdentityCommand`.
+
+An unattributed request reports the configured default caller, or the account root when no default
+caller is configured. An anonymous caller receives `AccessDenied`.
 
 ## Role-to-Role assumption
 
-Pass a caller to assume a Role as a specific principal. As in real AWS, both sides of the request
-are then evaluated:
+Pass `caller` to assume a role as a specific principal. STS checks both sides of the request:
 
 - The target Role's trust policy must allow the caller to perform `sts:AssumeRole`
 - A non-root caller also needs an identity policy allowing `sts:AssumeRole` on the target Role's
@@ -144,33 +145,25 @@ const assumeRoleOutput = await account.sts().assumeRole(
 console.log(assumeRoleOutput.AssumedRoleUser?.Arn);
 ```
 
-STS throws an AWS-like access-denied error if either side denies the request, which happens when the
-trust policy does not cover the caller, the caller has no identity policy allowing `sts:AssumeRole`,
-or an explicit `Deny` matches. The error has a `403` status code and names the `sts:AssumeRole`
-action and the target Role ARN. No session is created.
+If either check fails, STS raises a 403 access-denied error naming `sts:AssumeRole` and the target
+role ARN. No session is created.
 
-Cross-Account assumption works the same way. Create the source and target Roles in different
-simulated Accounts of the same `SimAws` instance, and call `assumeRole` on the source Account's
-`sts()`. The issued session belongs to the target Role's Account.
+Cross-account assumption uses the same checks. Call `assumeRole` through the source account. The
+session belongs to the target role's account.
 
 ## Role chaining
 
-A process that assumes a Role and then assumes a second one from that session is chaining Roles. The
-caller of the second request is the session, and the Role it holds the permissions of is what both
-sides of the decision are written against. The trust policy of the target names that Role, and the
-identity policy allowing `sts:AssumeRole` belongs to it.
+For role chaining, use the first session as the caller of the second `assumeRole` request. The target
+trust policy names the first role, and that role needs identity permission to assume the target.
 
-Both ARNs of a session are matched against a `Principal`, so a trust policy naming either the Role
-or one particular session admits it. AWS recommends naming the Role, and a session name is often
-decided at run time rather than written into a policy.
+A trust policy may name the role ARN or one assumed-role session ARN. Prefer the role ARN when the
+session name is chosen at run time.
 
-Chaining over a served endpoint works the same way. Credentials from the first request sign the
-second, and the caller they resolve to carries the Role along with the session.
+The served endpoint resolves session credentials in the same way.
 
 ## ExternalId
 
-A trust policy can require an external ID through the `sts:ExternalId` condition key. The
-`ExternalId` supplied to `AssumeRoleCommand` is matched against it.
+A trust policy can require `sts:ExternalId`. Pass the matching `ExternalId` to `AssumeRoleCommand`.
 
 ```typescript sim-sts-external-id
 /**
@@ -214,14 +207,14 @@ const assumeRoleOutput = await account.sts().assumeRole(
 console.log(assumeRoleOutput.AssumedRoleUser?.Arn);
 ```
 
-An omitted or mismatched `ExternalId` leaves the trust-policy condition unmatched. The assume
-request is denied.
+An omitted or mismatched value denies the request.
 
 ## Available functionality
 
 Sim STS currently supports:
 
 - `AssumeRoleCommand`
+- `GetCallerIdentityCommand`
 - Trust-policy evaluation against the target Role's assume-role policy document
 - Identity-policy evaluation of the source caller, requiring `sts:AssumeRole` permission on the
   target Role
@@ -231,15 +224,9 @@ Sim STS currently supports:
 - Temporary credentials registered with the target Account's sim IAM, including session-token and
   expiry validation
 
-Unsupported STS options may be ignored or may throw errors depending on whether the simulator needs
-them to model the requested behaviour.
-
 ## Limitations
 
-Sim STS models Role assumption. Notable gaps:
-
-- `AssumeRoleCommand` is the only supported command. There is no `GetCallerIdentity`, federation, or
-  web-identity support
+- Federation, web identity and session-token commands are unsupported.
 - Session policies (`Policy` / `PolicyArns`), tags, and `SourceIdentity` requests are not evaluated
 - Condition support in trust policies is limited to the operators supported by
   [sim IAM](https://yulinsim.dev/services/iam/#policy-conditions)