@kensio/yulin-aws-simulation 1.17.0 → 1.18.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "yulin-aws-simulation",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "How to test AWS code well with the @kensio/yulin in-process simulator.",
   "author": {
     "name": "Kensio Software",

package/README.md

@@ -38,10 +38,10 @@ Unzip it into `.agents/skills/` and it is installed.
 
 ## What it covers
 
-**Deploy your real synthesized template.** Deploy the JSON CDK produced, with
-`deployTemplateFile({ templatePath, stackName })`. A construct change that breaks the system breaks
-the test. Do not hand-roll a wrapper that reads the file and calls `deployTemplate`: the file path
-is how Yulin finds the cloud assembly beside it. A wrapper loses staged CDK assets. `transform`
+**Deploy your real synthesized templates.** Deploy the JSON CDK produced, one template or several,
+with `deployTemplateFile({ templatePath, stackName })`. A construct change that breaks the system
+breaks the test. Do not hand-roll a wrapper that reads the file and calls `deployTemplate`: the file
+path is how Yulin finds the cloud assembly beside it. A wrapper loses staged CDK assets. `transform`
 handles what a simulation cannot resolve, such as an ARN carrying a real account or a hosted zone ID
 from a CDK lookup, and `watch` re-applies the file on change for dev servers. `deployCdkOut` deploys
 a whole cloud assembly, each Stack into the region its own environment names.
@@ -91,9 +91,13 @@ authorised a Lambda function URL invocation against `lambda:InvokeFunctionUrl` a
 CloudFront origin access control also needs `lambda:InvokeFunction`. The tests passed, the release
 went out, and the endpoint 403'd in production.
 
-**Deploy expensive context once per test file.** Vitest gives each file its own worker. A stack
-deployed in `beforeAll` is already isolated between files. Isolation inside the file comes from
-randomised names.
+**Share one simulation across the whole test suite.** Create one `SimAws`, deploy the application
+once and install one `SimSdk` interception layer in Vitest setup. Run the suite in one shared worker
+and module context. Tests use random resource names and identifiers while the simulated AWS state
+stays alive, in the same way they would use an AWS account or a LocalStack container. This should be
+the majority of the suite. Put tests that advance or change the shared simulation clock in a smaller
+isolated group, with a fresh Yulin setup for each test. Per-test and per-file simulations are
+supported for these exceptional cases.
 
 **Run the handler as a real simulated Lambda.** Bind an in-process handler to a template function
 and invoke the function through simulated Lambda. Its SDK calls are then routed into the simulation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin-aws-simulation",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "How to test AWS code well with the @kensio/yulin in-process simulator.",
   "keywords": [
     "agent-skills",

package/skills/yulin-aws-simulation/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yulin-aws-simulation
-description: Use the @kensio/yulin in-process AWS simulator well when testing AWS code, using it directly rather than building a harness around it, driving tests, local dev and production from one synthesized CDK template, deploying a whole cdk.out cloud assembly, intercepting SDK clients with SimSdk, driving HTTP requests into the simulation with SimAwsHttp, controlling simulated time, matching service errors by name, and handling properties Yulin refuses to simulate. Use when writing or reviewing tests that touch AWS, when replacing aws-sdk-client-mock or hand-rolled AWS stubs, when a CDK stack needs testing, when a CloudFront Distribution, its DNS records or its certificate need testing, when test setup around Yulin is growing helper classes or wrapper functions, and when Yulin refuses a template property or an SDK command.
+description: Use the @kensio/yulin in-process AWS simulator well when testing AWS code. Share one simulation and SDK interception layer across tests that leave simulated time alone, and isolate the minority that change the clock. Use Yulin directly, deploy CDK-synthesized templates, bind real handlers, intercept SDK clients, drive HTTP with SimAwsHttp, control time, read generated names, match service errors by name, and handle unsupported properties. Use when writing or reviewing tests that touch AWS, replacing SDK stubs, testing CDK stacks or CloudFront resources, simplifying Yulin test setup, or diagnosing unsupported templates and commands.
 license: Apache-2.0
 metadata:
-  version: "1.17.0"
+  version: "1.18.1"
 ---
 
 # Testing with Yulin
@@ -13,6 +13,13 @@ network and no AWS account. This skill is how to use it well. It serves `isolate
 the general argument for simulation over stubs. Each rule says what it buys, and a case that does
 not want that trade can go the other way knowingly.
 
+Treat Yulin as suite infrastructure, in the same way tests treat an AWS account or a LocalStack
+container. Create one simulation, deploy the application once and install SDK interception once in
+the Vitest suite setup. Every test talks to that shared environment. Randomised resource names and
+identifiers keep tests independent while the simulated AWS state remains alive for the whole suite.
+This is the default for tests that leave the simulation clock alone. Put the smaller set of tests
+that change simulated time in an isolated group, with their own Yulin setup.
+
 For the API read `node_modules/@kensio/yulin/llms.txt`. It indexes the 45 markdown pages beside it
 under `node_modules/@kensio/yulin/docs/`, one per simulated service and per feature guide,
 documenting the version installed. Open the page it names for the service in hand and grep it for
@@ -29,18 +36,19 @@ service, or a `beforeEach` that reassembles the world.
 
 Yulin is built to be used directly. `new SimAws()` and `new SimSdk()` are plain constructors with no
 side effects, no network, no cleanup and no awaiting. Service accessors take the same Command
-objects the SDK does. `using simSdk = new SimSdk()` is the teardown, `deployTemplateFile` is the
-environment, and a simulation per test is close to free.
+objects the SDK does. The suite setup creates these objects once. `deployTemplateFile` is the
+environment, and the tests import the shared simulation objects directly.
 
-So a test constructs, deploys if a template is involved, intercepts, exercises, then asserts by
-reading the simulation back. A wrapper around any of those steps hides the one thing the reader
-needs to see. A repeated sequence can be a small function in the same file returning the simulation
-objects themselves. Once it wants a class, an options interface or a directory, it has become a
-second product.
+The setup constructs, deploys and intercepts. A test exercises the application and reads the shared
+simulation back. A wrapper around any of those steps hides what the reader needs to see. The setup
+can be a small module returning the simulation objects themselves. Once it wants a class, an options
+interface or a directory, it has become a second product.
 
-## One synthesized template, for tests, local dev and production
+## One CDK app behind the tests, local dev and production
 
-Describe the infrastructure once in CDK and let the synthesized output drive all three:
+Describe the infrastructure once in CDK and let the synthesized output drive all three. Deploy the
+template files `cdk synth` wrote, one of them or all of them, and talk to the simulation the way
+production talks to AWS.
 
 ```typescript
 const stack = await simAws.region("eu-west-2").cloudFormation().deployTemplateFile({
@@ -51,10 +59,12 @@ const stack = await simAws.region("eu-west-2").cloudFormation().deployTemplateFi
 await stack.waitForDeployComplete();
 ```
 
-A test written against a hand-written template only tests the hand-written template, and a dev
-environment building its own buckets is a third description whose drift shows up as a bug
-reproducing in exactly one of the three places. So infrastructure belongs in the CDK app even when
-only a test needs it.
+The test suite deploys this template once during its shared Yulin setup. Individual tests use the
+deployed resources and do not deploy their own copies.
+
+A hand-written template only tests itself, and a dev environment building its own buckets is a third
+description whose drift shows up as a bug reproducing in one place of the three. Infrastructure
+belongs in the CDK app even when only a test needs it.
 
 **Do not hand-roll a wrapper that reads the file and calls `deployTemplate`.** `deployTemplateFile`
 locates the cloud assembly beside the file, and that is how staged CDK assets resolve. A wrapper
@@ -76,14 +86,32 @@ await simAws.cloudFormation().deployTemplateFile({
 });
 ```
 
-Together they retire the derived template file a dev server used to write into `cdk.out` so that it
-had something to watch. The watched file is the one CDK wrote, and the adaptation re-applies on
-every read.
+The watched file is the one CDK wrote, and the adaptation re-applies on every read.
 
 `stack.output("SiteBucketName")` answers a resolved Output narrowed to a string, throwing on one the
-template never declared. Do not hand-roll that reader. And note that a failed `cdk synth` leaves the
-previous template in `cdk.out` with the tests still passing against it, so check the synthesized
-JSON changed before concluding anything from a construct change.
+template never declared. Do not hand-roll that reader. A failed `cdk synth` leaves the previous
+template in `cdk.out` with the tests still passing against it, so check the synthesized JSON changed
+before concluding anything from a construct change.
+
+### Read a generated name back, never write one out
+
+A Resource whose template leaves its name out is named `<stack name>-<logical ID>-<tail>`, as an
+account names one. The tail is twelve lowercase hex characters derived from the other two parts,
+standing in for the twelve random ones real CloudFormation appends. Where the two parts overrun the
+service's limit, thirteen characters of it go to the tail and its hyphen and the rest is shared
+between them (a 64 character limit leaves 25 each). The trimmed stack name is what an IAM policy
+scoped by resource prefix matches, and a deploy Role allowed an action on `MyVeryLongStackName-*` is
+refused here as an account refuses it.
+
+The same template under the same stack name generates the same name every time. That is the one
+property tempting a test to write the name out. Read it back instead, from a `Ref`, from an
+`Fn::GetAtt` attribute or from the accessor of the service holding it.
+[Names CloudFormation generates](https://yulinsim.dev/services/cloudformation/#names-cloudformation-generates)
+covers the tail and the trimming.
+
+An ECS container binding has no way round this. The family CloudFormation generates for an unnamed
+task definition ends in a tail only a deployment reveals. Name the task definition Resource with the
+`logicalId` binding form.
 
 ### Register what the app looks up, deploy what the app creates
 
@@ -93,12 +121,11 @@ simulated resource carrying it comes from. Yulin stands one up at a chosen id wi
 `simAws.acm().registerCertificate({ arn, domainName })`,
 `simAws.cognitoIdentityProvider().registerUserPool({ id, name })` and `registerUserPoolClient`.
 
-A registration creates a resource in place of the app creating one, and that is what decides when to
-use it. It suits `HostedZone.fromLookup` or a certificate issued by hand outside the app. A resource
-some stack in the same app creates wants deploying, since a registration would mean configuring it
-by hand and taking its configuration from somewhere other than the deployed template. So register
-what the app looks up, deploy what the app creates, and substitute in a `transform` only where a
-deployed resource cannot be given the id its template names.
+A registration creates a resource in place of the app creating one. It suits `HostedZone.fromLookup`
+or a certificate issued by hand outside the app. A resource some stack in the same app creates wants
+deploying instead, since a registration takes its configuration from somewhere other than the
+deployed template. Substitute in a `transform` only where a deployed resource cannot be given the id
+its template names.
 
 Route 53 needs least of this. An `AWS::Route53::RecordSet` naming a hosted zone id no zone holds
 gets one registered under that id as the record is created, taking its name from the records naming
@@ -128,9 +155,9 @@ const stacks = await simAws.cloudFormation().deployCdkOut({
 `stackNames` picks part of an assembly, which most apps need, since most also synthesize a
 deployment pipeline. `stackOptions` carries the `bindings`, `parameters` and `transform` that
 `deployTemplateFile` takes for one template, keyed the same way. Its transform is handed the Stacks
-the same call has already deployed. A Stack consuming a sibling's value therefore stays inside one
-call. Two Stacks passing a plain string between them declare no dependency for the manifest to
-carry, and the order they are named in is what puts the value there in time.
+the same call already deployed, so a Stack consuming a sibling's value stays inside one call. Two
+Stacks passing a plain string between them declare no dependency for the manifest to carry, and
+their order in `stackNames` is what puts the value there in time.
 
 ## Intercept real SDK clients, never hand-roll stubs
 
@@ -138,7 +165,7 @@ carry, and the order they are named in is what puts the value there in time.
 from the simulation, and the code under test uses the SDK exactly as it does in production.
 
 ```typescript
-using simSdk = new SimSdk();
+const simSdk = new SimSdk({ simAws });
 simSdk.intercept(SecretsManagerClient); // Every instance, including ones made later.
 ```
 
@@ -147,33 +174,31 @@ correctly. A stub has no naming rules and verifies no signatures. A malformed Se
 or a wrongly computed Cognito `SECRET_HASH` passes it and fails in production.
 
 Intercept the class in most cases, since the code under test usually constructs its own clients.
-Intercept an instance when a single client should reach the simulation, and when a file's cases each
-build their own `SimAws`. A class interception is process-wide (it shadows `send` on the class
-prototype) and refuses a second install while the first is live, with
-`SimSdkAlreadyInterceptedError`. An instance interception goes when the instance does.
+Install that class interception once in the suite setup. A class interception is process-wide (it
+shadows `send` on the class prototype) and refuses a second install while the first is live, with
+`SimSdkAlreadyInterceptedError`. Repeated interception in `beforeEach` or in each test file is both
+unnecessary and an error when those files share a worker. Intercept an instance only when one
+specific client should reach Yulin.
 
 Whichever it is, it has to be the client the code actually calls. A `DynamoDBDocumentClient` built
 over a `DynamoDBClient` is what the code sends through, and the document client is the one to
 intercept. Every Command routes to the simulation by default, and an allow list of Command classes
 narrows that where something else should handle the rest.
 
-`SimSdk` and its interception handles are disposable, so `using` restores every intercepted client
-at the end of the scope, leaving nothing for a later test to inherit when the one before it threw.
-`simSdk.restoreAll()` and `interception.restore()` do it by hand. Each `SimSdk` owns a `SimAws`,
-reachable as `simSdk.simAws`, and `new SimSdk({ simAws })` shares an existing one.
+Keep the suite's `SimSdk` alive for as long as the suite. Worker exit normally removes its
+process-wide patches. Call `simSdk.restoreAll()` if the process will continue doing other work.
+`using simSdk = new SimSdk()` and `interception.restore()` remain useful for a deliberately
+short-lived simulation. Each `SimSdk` owns a `SimAws`, reachable as `simSdk.simAws`, and
+`new SimSdk({ simAws })` shares an existing one.
 
 ### A fake accepts any request the simulator would refuse
 
 A fake S3 client stubbing `send` with canned `ListObjectsV2` pages, asserted on through the
 continuation tokens it recorded, passes for code that built its command without a `Bucket`.
-Simulated S3 does the pagination for real. `Prefix`, `MaxKeys`, `ContinuationToken` and `StartAfter`
-all apply, `IsTruncated` and `NextContinuationToken` come back as the service sends them, and
+Simulated S3 paginates for real, down to the ETag a real multipart upload produces, and
 `configureMaxKeysPerPage` lowers the page size so that a bucket of two objects makes a caller walk a
-continuation. Uploading real parts gives the object the real `<md5-of-the-part-md5s>-<count>` ETag.
-
-The residue is small. A couple of answers the service never sends (a truncated page naming no
-continuation token) can only come from a fake, and a test reaching for one should say so in a
-comment.
+continuation. The residue is small, and a test reaching for a fake to get an answer the service
+never sends should say so in a comment.
 
 ## Freeze the clock and advance it deliberately
 
@@ -189,17 +214,30 @@ const simAws = new SimAws({
 await simAws.clock().advanceBy({ minutes: 20 });
 ```
 
-Time-dependent behaviour then becomes something a test asserts on in microseconds. A good deal of
-the simulation keys off that clock. EventBridge rules and Scheduler schedules fire only when time is
-advanced past them, DynamoDB items pass their TTL, Secrets Manager deletions come due, `AssumeRole`
-sessions expire, Lambda event source mappings re-poll, and inside a simulated Lambda `Date.now()`
-and `new Date()` report simulated time. So the clock stub `isolated-testing-style` allows is
-unnecessary here, since advancing this one exercises the real expiry rules of the services around it
-as well as the code's own arithmetic.
+Time-dependent behaviour then becomes something a test asserts on in microseconds, and a good deal
+of the simulation keys off that clock. EventBridge rules and Scheduler schedules fire only when time
+is advanced past them, DynamoDB items pass their TTL, Secrets Manager deletions come due,
+`AssumeRole` sessions expire, Lambda event source mappings re-poll, and inside a simulated Lambda
+`Date.now()` and `new Date()` report simulated time. The clock stub `isolated-testing-style` allows
+is unnecessary here, since advancing this one exercises the real expiry rules of the services around
+it as well as the code's own arithmetic.
 
 `simAws.clock().resume()` tracks the underlying clock and `simAws.clock().isFrozen` reports the
 mode. Running mode suits a local dev server, and a test usually wants an advance.
 
+### Give clock-changing tests their own simulation
+
+The clock is part of a `SimAws` instance's state. Tests sharing that instance also share its current
+time and whether it is frozen or running. One test advancing or resuming the clock therefore changes
+the environment underneath every other test in that group. Randomised resource names cannot isolate
+this change.
+
+Most tests should use the suite simulation without changing its clock. Put tests that advance the
+clock or change its mode in a separate Vitest project or file group. Give each of those tests a
+fresh `SimAws`, deployment and interception layer. Each test can then control time without affecting
+another test. A small group may share one isolated simulation when its cases deliberately follow the
+same timeline.
+
 ## Assert by reading the simulation back
 
 The simulation holds real state. After exercising the code, ask the service what happened:
@@ -211,13 +249,14 @@ const object = await simAws.s3().getObject(new GetObjectCommand({ Bucket: bucket
 
 A call-count assertion holds only for today's implementation. A state assertion holds however the
 handler is rewritten, and it fails if the call was made in a way the real service would have
-rejected.
+rejected. In the shared suite environment, read the resource named by the test's random identifier.
+Do not list the whole service and assume no other test has left state there.
 
-The accessors sit on more than one scope, with `simAws.region(name)` carrying some of the services
-and `simAws.region(name).account()` carrying all of them (`logs()` among the ones only the account
-scope has), so look on the other scope before concluding a service is missing. Each also takes a
-plain `{ input: { ... } }` in place of a Command object. An assertion can therefore read a service
-back without adding an `@aws-sdk/client-*` package the production code has no use for.
+The accessors sit on more than one scope. `simAws.region(name)` carries some of the services and
+`simAws.region(name).account()` carries all of them (`logs()` among the account-only ones), so look
+on the other scope before concluding a service is missing. Each also takes a plain
+`{ input: { ... } }` in place of a Command object. An assertion can then read a service back without
+adding an `@aws-sdk/client-*` package the production code has no use for.
 
 ## Drive requests into the simulation
 
@@ -238,11 +277,11 @@ A hostname simulated Route 53 answers for is requested by its own name, with no
 `localUrl(...)` adapting (an `https` URL works with no certificate set up for it). That one request
 resolves the hostname, finds the Distribution its alias records point at, and runs the deployed
 CloudFront Function at viewer-request. The certificate, the Hosted Zone records, the Distribution's
-aliases and the function are covered together. A template assertion over the same stack passes with
-every Route 53 record missing.
+aliases and the function are covered together, where a template assertion over the same stack passes
+with every Route 53 record missing.
 
-Reach for `serveSimAws` when the request comes from outside the process, such as a browser, `curl`
-or an SDK client pointed at a local endpoint. Both go through the same routing and service code, and
+Reach for `serveSimAws` when the request comes from outside the process (a browser, `curl`, an SDK
+client pointed at a local endpoint). Both go through the same routing and service code, and
 `SimAwsHttp` leaves parallel test files no port to collide over. See
 [the serving docs](https://yulinsim.dev/serve/) for the API.
 
@@ -257,9 +296,9 @@ if (error instanceof Error && error.name === "ResourceNotFoundException") { ...
 ```
 
 The SDK exports exception classes, which invites the `instanceof` check. It holds only while exactly
-one copy of the SDK package is in play. Two copies in the module graph, a bundler, or a simulator
-raising its own classes, and it silently stops matching. Yulin's errors carry the service's real
-error names and SDK-shaped `$metadata` without being instances of the SDK classes. Fix it in
+one copy of the SDK package is in play, and two copies in the module graph, a bundler, or a
+simulator raising its own classes all stop it matching silently. Yulin's errors carry the service's
+real error names and SDK-shaped `$metadata` without being instances of the SDK classes. Fix it in
 production code, where a version skew between two `@aws-sdk/client-*` packages breaks `instanceof`
 too. `name` is what the wire carries, and is right in both places.
 
@@ -283,47 +322,101 @@ workaround has to be maintained in every project that hits the same gap.
 
 The asymmetry matters more than the volume. A simulator staying silent about something costs little,
 leaving that behaviour uncovered where it already was. A simulator saying 200 where production says
-403 turns a deploy-time failure into a production one, the opposite of what it is for. So report a
-false pass with what production does and what the simulation did, and a false refusal with the
-property and the template that carries it. Raise a gap costing nothing but convenience as well, once
-it is forcing structural duplication.
+403 is the opposite of what it is for. So report a false pass with what production does and what the
+simulation did, and a false refusal with the property and the template that carries it. Raise a gap
+costing nothing but convenience as well, once it is forcing structural duplication.
 
 A workaround kept while the issue is open wants a comment naming that issue and a revisit when it
-closes. Re-read the claims in your own comments on each upgrade. They are the ones nothing tests.
+closes. Re-read those claims on each upgrade. They are the ones nothing tests.
+
+## Share one simulation across the whole test suite
 
-## Deploy expensive context once per test file
+The recommended lifecycle is one `SimAws`, one deployment and one `SimSdk` interception layer for
+the tests that do not change simulated time. This should be most of the test suite. Do this in
+Vitest setup. Tests should treat the result as a long-running AWS account or LocalStack container
+whose state survives every test and test file.
 
-Vitest gives each test file its own worker, so module-level state is already isolated between files.
-Deploy a stack once for the file and let the tests share it. Isolation inside the file comes from
-randomised names.
+An in-process simulation needs the test files to share a worker and module cache. Set
+`fileParallelism: false` and `isolate: false`, then load one setup module through `setupFiles`:
 
 ```typescript
-let simAws: SimAws;
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    fileParallelism: false,
+    isolate: false,
+    setupFiles: ["./test/yulin.setup.ts"],
+  },
+});
+```
+
+Keep the one-time work in an imported module. Vitest executes a setup file before each test file,
+even with isolation disabled, but imported modules stay cached in the shared worker.
+
+```typescript
+// test/yulin-suite.ts
+const ready = (async () => {
+  const simAws = new SimAws();
+  const simSdk = new SimSdk({ simAws });
+
+  simSdk.intercept(DynamoDBClient);
+  simSdk.intercept(S3Client);
 
-beforeAll(async () => {
-  simAws = new SimAws();
   const stack = await simAws.cloudFormation().deployTemplateFile({
     templatePath: "cdk.out/SiteStack.template.json",
   });
   await stack.waitForDeployComplete();
-});
 
-it("stores an upload", async () => {
-  // Given a key no other test in this file is using.
-  const key = `uploads/${faker.string.uuid()}.png`;
-});
+  return { simAws, simSdk, stack };
+})();
+
+export function yulinSuite() {
+  return ready;
+}
+```
+
+```typescript
+// test/yulin.setup.ts
+import { yulinSuite } from "./yulin-suite";
+
+await yulinSuite();
 ```
 
-A template deployment is the only thing usually worth hoisting, and in `beforeEach` it pays for the
-whole stack once per test for no isolation you did not already have. The `SimSdk`, a seeded row and
-a bucket key belong inside the test that needs them. A `beforeEach` assembling state for tests that
-do not all want the same state is the beginning of the harness this skill opens by arguing against.
+Tests import `yulinSuite()` and work against that same state. Give every test data a random name or
+identifier, query by that identifier and never assume a service starts empty. A missing-resource
+case uses a new identifier that no test created. A count assertion records the relevant count before
+the action when it cannot query by identifier. Tests remain independent without clearing tables,
+buckets or queues between them.
+
+```typescript
+const { simAws } = await yulinSuite();
+const key = `uploads/${faker.string.uuid()}.png`;
+
+// Exercise the application, then read this test's object from shared S3 state.
+const object = await simAws.s3().getObject({ input: { Bucket: bucket, Key: key } });
+```
+
+Do not put the simulation in Vitest `globalSetup`. That hook runs outside the test workers and can
+only pass serializable values into them. `setupFiles` runs in the test worker and can share the live
+`SimAws` object through the cached module above.
+
+This shared setup also shares the simulation clock. Keep tests that call `advanceBy`, resume the
+clock or otherwise change simulated time out of this group. Put them in a separate Vitest project or
+file pattern, such as `*.clock.iso.test.ts`, and give each test an isolated Yulin setup. The split
+keeps the common suite setup cheap while allowing the smaller clock-testing group to control time.
+
+Creating Yulin once per test or once per file is supported. Reserve it for a case that deliberately
+tests an entire fresh account, an independent clock or incompatible interception. Use the shared
+setup by default. A `beforeEach` or file-level `beforeAll` that deploys the application again
+usually turns random test data into repeated infrastructure work.
 
-## Run the handler as a real simulated Lambda
+## Bind a handler and run it as a real simulated Lambda
 
-Yulin can run an in-process handler as a function inside the simulation. Bind it to a template
-function at deploy time with `bindings`, targeting the function by `logicalId`, `functionName`,
-`arn`, `cdkPath` or `imageRepository`:
+`bindings` is how to run your own code inside the simulation, for an `AWS::CloudFront::Function` as
+much as for a Lambda function. Bind an in-process handler at deploy time, targeting a Lambda
+function by `logicalId`, `functionName`, `arn`, `cdkPath` or `imageRepository`, and a CloudFront
+Function by `logicalId`, `functionName` or `arn`. On a CloudFront Function it is what covers source
+`cdk synth` embedded or transformed.
 
 ```typescript
 await simAws.cloudFormation().deployTemplateFile({
@@ -358,10 +451,10 @@ accessors. A recording logger was the last reason standing, and from 1.17.1 a bo
 is recorded into its log group, read back at `/aws/lambda/<function name>` through
 `FilterLogEvents`.
 
-The console and the process standard streams are both bridged for the length of an invocation, in
-the way `process.env` and `Date` are. A logging library building its own `Console` over those
-streams at module scope is recorded too, Powertools' `Logger` included, both its JSON log line and
-its EMF metric document.
+The console and the process standard streams are bridged for the length of an invocation, as
+`process.env` and `Date` are. A logging library building its own `Console` over those streams at
+module scope is recorded too, Powertools' `Logger` included, both its JSON log line and its EMF
+metric document.
 
 So when a test builds the application's own graph, ask what it cannot get through an invocation.
 Expect the answer to be nothing.
@@ -370,27 +463,30 @@ Expect the answer to be nothing.
 
 A bound handler gets the function's declared environment variables with nothing stubbed.
 `SimProcessEnvironment` holds a run's variables in an `AsyncLocalStorage` store and resolves
-`process.env` to it for the length of the run, with concurrent runs each seeing their own. The one
-thing it cannot reach is a read that already happened. A handler module doing
+`process.env` to it for the length of the run, with concurrent runs each seeing their own. What it
+cannot reach is a read that already happened. A handler module doing
 `const TABLE = process.env.TABLE_NAME` at module scope is evaluated when the test file imports it,
 long before any run, and captures the host value.
 
 So read the environment inside the handler body, memoising there where a warm container should build
-its clients once. The substituted `Date` works the same way. A `vi.stubEnv` around a bound handler
-is the sign of a handler reading too early. `SimLambdaEnvironmentConflicts` warns about this, but
-only where the host value and the declared value differ, and a suite that stubs the right values
-stays quiet and never learns.
+its clients once. The substituted `Date` works the same way, and a `vi.stubEnv` around a bound
+handler is the sign of a handler reading too early. `SimLambdaEnvironmentConflicts` warns about
+this, but only where the host value and the declared value differ, and a suite that stubs the right
+values stays quiet and never learns.
 
-### What a binding buys, and what the zip path buys
+### Keep the zip path for a case about the artefact
 
-Deploying without `bindings` runs the bundle `cdk synth` produced. `deployTemplateFile` publishes
-the cloud assembly's assets into the staging bucket in simulated S3, and the modules are evaluated
-as CommonJS in a vm sandbox with its own `process.env`, `Date` and HTTP clients, where the
-module-scope problem above never arises. Both paths authorise through the execution role, and the
-same policy mutation fails a zip-path test exactly as it fails a bound one.
+Deploying a Lambda function without `bindings` runs the bundle `cdk synth` produced.
+`deployTemplateFile` publishes the cloud assembly's assets into the staging bucket in simulated S3,
+and the modules are evaluated as CommonJS in a vm sandbox with its own `process.env`, `Date` and
+HTTP clients, where the module-scope problem above never arises. Both paths authorise through the
+execution role, and the same policy mutation fails a zip-path test exactly as it fails a bound one.
 
-- **A binding** keeps a breakpoint working and lets the handler close over test state.
-- **The zip path** exercises the artefact that deploys, its imports and its bundling included.
+What that buys is the artefact that deploys, its imports and its bundling included, and a case about
+the bundle itself is the case to spend it on. Everywhere else it is the fallback. Every run waits on
+the build, a stale `cdk.out` runs yesterday's handler, and the vm runtime loads CommonJS as the real
+`nodejs` runtimes do, leaving a `NodejsFunction` synthesized with `format: OutputFormat.ESM` refused
+at cold start.
 
 ### Outbound HTTP is answered by the simulation
 
@@ -398,7 +494,7 @@ From 1.16.2, a simulated Lambda's `fetch` and its `node:http` and `node:https` a
 simulation for every hostname simulated Route 53 resolves, through the same in-process entry point a
 request arriving on localhost uses. A Cognito user pool domain, an HTTP API and a load balancer are
 all answered without the test knowing which of them it asked, and everything else reaches the
-network as it was addressed. This is what makes an OAuth authorization code exchange testable, since
-that exchange lives only at the pool domain's hosted `/oauth2/token` endpoint with no SDK operation
-behind it. The same routing lets `CognitoJwtVerifier` fetch a simulated pool's JWKS from inside a
-handler with no cache primed.
+network as addressed. That is what makes an OAuth authorization code exchange testable, since it
+lives only at the pool domain's hosted `/oauth2/token` endpoint with no SDK operation behind it, and
+it lets `CognitoJwtVerifier` fetch a simulated pool's JWKS from inside a handler with no cache
+primed.