@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/athena/README.md

@@ -1,22 +1,15 @@
 # Simulated Athena
 
-Yulin includes a simulated Amazon Athena for tests and local development. It holds workgroups and
-named queries, and hands both back through the SDK.
+Yulin simulates Amazon Athena workgroups, named queries and query execution for tests and local
+development. Tests can supply a result for a particular SQL statement, or enable the optional
+[query engine](#running-a-query-for-real) to run SQL against objects in simulated S3.
 
-A query is answered one of two ways. A test declares what it answers with, and the simulation
-matches that declaration on the query text. Or the
-[query engine](#running-a-query-for-real) runs the SQL for real over the objects a test seeded into
-simulated S3. The engine is off until a test turns it on, and it needs one package added to the
-project.
+Both paths use the same query lifecycle. Athena checks tables in the simulated
+[Glue Data Catalog](https://yulinsim.dev/services/glue/ "Simulated Glue usage docs"), applies the
+workgroup's bytes-scanned limit and writes results to the configured S3 location. This lets client
+code start a query, poll its status and read its results through the AWS SDK.
 
-Either way the lifecycle around the query is real. A test can prove its bytes-scanned cutoff
-refuses a query, that results land where the workgroup says, and that a client polls the lifecycle
-correctly. The tables a query names are looked for in the simulated
-[Glue Data Catalog](https://yulinsim.dev/services/glue/ "Simulated Glue usage docs"), and a query
-naming one that is absent fails the way real Athena fails it. The
-[Limitations](#limitations) at the end say what this leaves out.
-
-Athena-specific types are imported from the `@kensio/yulin/athena` subpath.
+Import Athena-specific types from `@kensio/yulin/athena`.
 
 ## Workgroups from a template
 
@@ -177,23 +170,21 @@ const results = await simAws.athena().getQueryResults({
 console.log(results.ResultSet?.Rows?.[1]?.Data?.[1]?.VarCharValue);
 ```
 
-A rule for an exact query wins, then a rule for a workgroup, then the default. `onWorkGroup` covers
-every query a stack's rollups run, and `byDefault` covers everything else. Matching is exact, on the
-query text as it was sent, so two queries differing only in whitespace are two different keys.
+A result declared for an exact query takes precedence over a workgroup result, which takes
+precedence over the default result. Use `onWorkGroup` to cover every query in one workgroup and
+`byDefault` as the fallback. Exact matching includes whitespace.
 
 The query engine sits between the two tiers. A rule for an exact query is ahead of it and the
 workgroup rule and the default are behind it.
 
-`failsWith` fails a query instead of answering it. Nothing here reads SQL, so a query that should
-fail cannot be discovered on its own. Saying so is what makes a client's failure handling
-reachable.
+Use `failsWith` to declare a failed query and test the client's error handling. Declared results do
+not parse the SQL, so failures must be configured explicitly.
 
 ## Running a query for real
 
-The query engine answers a `SELECT` from the objects a test seeded into simulated S3. It reads the
-table's schema out of the Glue Data Catalog, decodes each object with the SerDe the table declares,
-loads the rows into an in-memory SQLite database, and answers the statement from them. Roughly
-nineteen queries in twenty of the shapes a test writes run this way.
+The query engine runs a `SELECT` against objects seeded into simulated S3. It reads the table schema
+from the Glue Data Catalog, decodes each object with the table's SerDe, loads the rows into an
+in-memory SQLite database and executes the statement.
 
 The engine is off until a test turns it on, and it needs `node-sql-parser` in the project. The
 parser is an optional peer dependency, so a project that never runs a query never installs it. A
@@ -965,7 +956,7 @@ Every command is authorized against the workgroup ARN,
 own and authorizes work on one against the workgroup it belongs to. This asks the same question.
 `ListWorkGroups` names no workgroup, so IAM evaluates it against `*`.
 
-## Available functionality
+## Supported operations
 
 - Query executions, moving through `QUEUED` and `RUNNING` to `SUCCEEDED`, `FAILED` or `CANCELLED`
 - `StartQueryExecution`, `GetQueryExecution`, `GetQueryResults` and `StopQueryExecution`

package/docs/services/backup/README.md

@@ -1,12 +1,12 @@
 # Simulated AWS Backup
 
-Yulin includes simulated AWS Backup vaults, plans, selections, backup jobs and recovery points for
-tests and local development. AWS Backup types are imported from the `@kensio/yulin/backup` subpath.
+Yulin simulates AWS Backup vaults, plans, selections, jobs and recovery points. Import Backup types
+from `@kensio/yulin/backup`.
 
 ## Creating a vault, plan and selection
 
-`simAws.backup()` gives the AWS Backup service for the default account and Region. A plan rule names
-an existing vault. A selection belongs to one plan and records the resource ARNs assigned to it.
+Use `simAws.backup()` for the default account and Region. Each plan rule names an existing vault. A
+selection assigns resource ARNs to a plan.
 
 ```typescript sim-backup-create-plan-selection
 /**
@@ -78,19 +78,17 @@ console.log(selection.BackupSelection?.Resources);
 // ["arn:aws:dynamodb:us-east-1:888888888888:table/orders"]
 ```
 
-A plan needs at least one rule. Every rule needs a name and a target vault. An omitted schedule uses
-`cron(0 5 ? * * *)`, the AWS Backup default. Six-field AWS cron expressions and rate expressions
-are validated when the plan is created. A one-time `at(...)` expression is refused.
+A plan needs at least one named rule and target vault. The default schedule is
+`cron(0 5 ? * * *)`. Yulin accepts six-field AWS cron expressions and rate expressions. It rejects
+`at(...)` expressions.
 
-`MoveToColdStorageAfterDays` can be combined with `DeleteAfterDays`. The deletion must be at least
-90 days after the move to cold storage. A shorter lifecycle raises
-`InvalidParameterValueException`. Set both values to `-1` to retain recovery points indefinitely.
+When both lifecycle values are set, `DeleteAfterDays` must be at least 90 days after
+`MoveToColdStorageAfterDays`. Use `-1` for both values to keep recovery points indefinitely.
 
 ## Running scheduled backups
 
-Each plan rule runs on the simulated clock. A due rule creates one recovery point for each distinct
-resource ARN in the plan's selections. The recovery point records the rule, resource ARN, lifecycle
-and creation time. The simulation completes backup jobs at the scheduled instant.
+Plan rules run on the simulated clock. A due rule creates one completed job and recovery point for
+each distinct resource ARN in its selections.
 
 ```typescript sim-backup-run-schedule
 /**
@@ -161,19 +159,16 @@ console.log(points.RecoveryPoints?.[0]?.ResourceArn);
 console.log(jobs.BackupJobs?.[0]?.State); // "COMPLETED"
 ```
 
-`DeleteAfterDays` removes a recovery point when the clock reaches its deletion time. Vault reads,
-`ListRecoveryPointsByBackupVault` and `DescribeRecoveryPoint` apply the expiry before returning.
-Repeated schedules keep every unexpired recovery point.
+`DeleteAfterDays` removes a recovery point when simulated time reaches its expiry. Recovery point
+reads apply expiry before returning.
 
-Vault Lock bounds apply when a backup starts. A lifecycle shorter than `MinRetentionDays`, longer
-than `MaxRetentionDays` or indefinite under a finite maximum produces a `FAILED` backup job. The
-vault receives no recovery point for that job. Use `ListBackupJobs` or `DescribeBackupJob` to read
-the failure and its `StatusMessage`.
+Vault Lock bounds are checked when a backup starts. An invalid lifecycle produces a `FAILED` job and
+no recovery point. Read the reason from the job's `StatusMessage`.
 
 ## Starting an on-demand backup
 
-`StartBackupJob` completes an on-demand job at the current simulated time. It applies the same
-lifecycle validation and Vault Lock bounds as a scheduled rule.
+`StartBackupJob` completes at the current simulated time. It applies the same lifecycle and Vault
+Lock checks as a scheduled job.
 
 ```typescript sim-backup-start-job
 /**
@@ -219,9 +214,8 @@ console.log(point.CreationDate?.toISOString());
 
 ## Vault Lock
 
-`PutBackupVaultLockConfiguration` records minimum and maximum retention periods on a vault. Adding
-`ChangeableForDays` creates a compliance lock. The configuration stays changeable until the grace
-period ends, then becomes immutable.
+`PutBackupVaultLockConfiguration` sets minimum and maximum retention. `ChangeableForDays` adds a
+grace period. The configuration becomes immutable when that period ends.
 
 ```typescript sim-backup-vault-lock
 /**
@@ -284,8 +278,7 @@ exceed the maximum, and the maximum cannot exceed 36,500 days. A lock without
 ## Deploying from CloudFormation
 
 Simulated CloudFormation deploys `AWS::Backup::BackupVault`, `AWS::Backup::BackupPlan` and
-`AWS::Backup::BackupSelection`. References between the resources resolve before AWS Backup creates
-them.
+`AWS::Backup::BackupSelection`.
 
 ```typescript sim-backup-cloudformation
 /**
@@ -376,10 +369,9 @@ Stack teardown removes all three resource types from the simulation.
 
 ## Permissions
 
-Every supported operation is authorized by simulated IAM. Vault operations use the vault ARN. Plan
-and selection operations use the plan ARN. `ListBackupVaults` has no resource in its request and is
-authorized against `*`. `StartBackupJob` and `ListRecoveryPointsByBackupVault` use the vault ARN.
-`DescribeRecoveryPoint` uses the recovery point ARN. Backup job reads use `*`.
+Every supported operation uses simulated IAM. Vault operations authorize against the vault ARN.
+Plan and selection operations use the plan ARN. `DescribeRecoveryPoint` uses the recovery point ARN.
+List and backup job read operations that name no resource use `*`.
 
 ```typescript sim-backup-iam-policy
 /**
@@ -432,13 +424,12 @@ const created = await simAws.backup().createBackupVault(
 console.log(created.BackupVaultName); // "application-backups"
 ```
 
-Authorization runs before resource lookup. An unauthorized request for a missing vault or plan
-raises `AccessDeniedException`, without revealing whether the resource exists.
+Authorization runs before resource lookup. An unauthorized request for a missing resource raises
+`AccessDeniedException`.
 
 ## SDK interception
 
-`SimSdk` routes commands from an AWS `BackupClient` to the simulation. Intercept the client instance
-when a test owns it, or intercept the class when application code creates the client.
+Intercept a `BackupClient` instance or the client class to route SDK commands to Yulin.
 
 ```typescript sim-backup-sdk-interception
 /**
@@ -466,13 +457,12 @@ console.log(listed.BackupVaultList?.[0]?.BackupVaultName);
 // "application-backups"
 ```
 
-The client's configured Region selects the simulated Region. Credentials select the account and
-caller when the intercepted client has them. See the [SDK interception docs](https://yulinsim.dev/sdk/)
-for class interception and credential handling.
+Client Region and credentials select the simulated scope and caller. See
+[SDK interception](https://yulinsim.dev/sdk/) for details.
 
 ## Account and Region scoping
 
-AWS Backup state belongs to one account and Region. The same vault name can exist in another scope.
+Backup state is scoped by account and Region. The same vault name can exist in another scope.
 
 ```typescript sim-backup-account-region-scoping
 /**

package/docs/services/bedrock/README.md

@@ -1,14 +1,14 @@
 # Simulated Bedrock
 
-Simulated Bedrock answers model invocations from responses declared against a prompt or a model. A
-test says what the model says, and no model runs.
+Yulin answers Bedrock Runtime requests from response rules declared by the test. Model responses
+come entirely from those rules.
 
 Bedrock-specific types are imported from the `@kensio/yulin/bedrock` subpath.
 
 ## Answering a conversation
 
-`Converse` answers with the response declared for the prompt it carries. The prompt is the text of
-the last user message.
+Declare a response with `onPrompt`, then call `converse`. The prompt is the text of the last user
+message.
 
 ```typescript sim-bedrock-converse
 /**
@@ -37,13 +37,12 @@ console.log(answered.output.message.content.at(0)?.text);
 console.log(answered.stopReason); // "end_turn"
 ```
 
-A conversation with several turns matches on its last user message, so a rule keeps matching as the
-conversation grows.
+A multi-turn conversation also matches its last user message.
 
 ## Answering every call to one model
 
-`onModel` covers every invocation of a model that no prompt rule matched first. This is the rule for
-a test that cares about the code around the call rather than about one exchange.
+Use `onModel` when every call to one model should receive the same response. Prompt rules take
+precedence over model rules.
 
 ```typescript sim-bedrock-model-rule
 /**
@@ -71,13 +70,13 @@ const answered = await simAws.bedrock().converse(
 console.log(answered.output.message.content.at(0)?.text); // "A short summary."
 ```
 
-`byDefault` covers everything else again. An invocation matching no rule at all answers with a
-built-in line of text that says it is simulated.
+`byDefault` handles calls that match no prompt or model rule. With no matching declaration, Yulin
+returns a built-in simulated response for `Converse`.
 
 ## Answering with a tool call
 
-A declared response carries content blocks as they were written, so a tool call reaches the code
-that handles one. The response stops for `tool_use` unless the declaration names another reason.
+Declare a `toolUse` content block to test code that handles model tool calls. The default stop reason
+for this response is `tool_use`.
 
 ```typescript sim-bedrock-tool-use
 /**
@@ -119,8 +118,8 @@ console.log(answered.output.message.content.at(0)?.toolUse?.name);
 
 ## Streaming a conversation
 
-`ConverseStream` answers from the same rules, and sends the response as the events real Bedrock
-sends. Declaring `chunks` says where the deltas fall.
+`ConverseStream` uses the same rules as `Converse`. Declare `chunks` to control the text in each
+stream event.
 
 ```typescript sim-bedrock-converse-stream
 /**
@@ -156,14 +155,11 @@ for await (const event of answered.stream) {
 console.log(accumulated); // "Entry 1042 covers the tone sandhi rules."
 ```
 
-The events arrive in the order real Bedrock sends them. `messageStart`, then one
-`contentBlockDelta` per chunk, then `contentBlockStop`, `messageStop` carrying the stop reason, and
-`metadata` carrying the token counts. A tool call adds a `contentBlockStart` before its delta,
-carrying the tool use id and name.
+The stream contains `messageStart`, content block events, `messageStop` and `metadata`. Tool calls
+also include `contentBlockStart` with the tool use ID and name.
 
-The same declaration serves both APIs. `Converse` answers with the chunks joined, and a response
-declared as `text` streams as a single delta. A stream is readable once, and reading it again
-raises.
+The same declaration serves both APIs. `Converse` joins declared chunks. Plain `text` becomes one
+stream delta. A stream can be read once.
 
 `InvokeModelWithResponseStream` streams the declared body as a single `chunk`:
 
@@ -175,8 +171,8 @@ for await (const event of answered.body) {
 
 ## Invoking a model directly
 
-`InvokeModel` answers with the body declared for the request, serialized as JSON. The body is the
-shape the model behind the id uses, which is why there is no built-in default for it.
+`InvokeModel` returns the declared `body` as JSON. The response shape depends on the model, so this
+operation has no built-in body.
 
 ```typescript sim-bedrock-invoke-model
 /**
@@ -207,12 +203,11 @@ console.log(JSON.parse(new TextDecoder().decode(answered.body)));
 // { results: [ { outputText: "Entry 1042 covers tone sandhi." } ] }
 ```
 
-An `InvokeModel` request matches a prompt rule on its request body decoded as UTF-8. A model rule is
-usually the one to reach for.
+Prompt rules match the UTF-8 request body. Model rules are usually simpler for this API.
 
 ## Reporting token counts
 
-`usage` comes from the declaration, and a response that declares none reports fixed counts.
+Set `usage` on a response rule to control token counts. Yulin uses fixed counts when it is omitted.
 
 ```typescript sim-bedrock-usage
 /**
@@ -245,14 +240,13 @@ console.log(answered.usage.totalTokens); // 1620
 
 ## Authorizing an invocation
 
-An invocation authorizes `bedrock:InvokeModel` against the model it names. A base model id becomes a
-foundation model ARN for the Region the call was made in, and an inference profile ARN or a
-provisioned model ARN is authorized against as it was written.
+Every invocation authorizes `bedrock:InvokeModel` against the requested model. A base model ID is
+converted to a foundation model ARN in the request Region. Model ARNs are used unchanged.
 
 ## SDK interception
 
-An intercepted `BedrockRuntimeClient` reaches the simulated Bedrock of the Account and Region the
-client is configured for.
+Intercept a `BedrockRuntimeClient` when application code constructs the client itself. Client
+credentials and Region select the simulated scope.
 
 ```typescript sim-bedrock-sdk-interception
 /**
@@ -296,32 +290,26 @@ simSdk.restoreAll();
 
 - `Converse`, `ConverseStream`, `InvokeModel` and `InvokeModelWithResponseStream`, through
   `simAws.bedrock()` and through an intercepted `BedrockRuntimeClient`.
-- Responses declared with `onPrompt`, `onModel` and `byDefault`. A prompt rule wins, then a model
-  rule, then the default.
+- Responses declared with `onPrompt`, `onModel` and `byDefault`, in that precedence order.
 - A declared response carries `text`, `chunks` or `content` blocks for `Converse`, a `body` for
   `InvokeModel`, and optionally a `stopReason` and a `usage`.
-- Streamed responses, with `chunks` deciding where the deltas fall and one declaration serving the
-  streaming and non-streaming APIs alike.
+- Streamed responses with caller-controlled chunks.
 - Tool calls, as a declared `toolUse` content block.
 - IAM authorization of `bedrock:InvokeModel` against the foundation model, inference profile or
   provisioned model ARN the request names.
-- Rules held per Account and Region, so two Regions answer the same prompt differently.
+- Rules scoped by account and Region.
 
 ## Limitations
 
-- No model runs. A response is whatever the matching rule declared, and the prompt is read only as
-  a key to match on.
+- No model runs. Yulin returns the matching declared response.
 - Every event of a stream is ready as soon as the call returns. Real Bedrock sends them as the model
   generates them. No simulated clock advance separates them here.
-- A response is split into deltas only where the declaration says so. Text declared any other way
-  arrives in one delta. The split a real model streams comes from its own tokenizer.
+- A response is split only at declared chunk boundaries. Other text arrives in one delta.
 - A streamed tool call sends its arguments in one delta. Real `ConverseStream` sends them as
   fragments of JSON to be concatenated. A tool call with no declared arguments sends `{}`.
 - `InvokeModelWithResponseStream` sends the declared body as a single chunk. Real Bedrock sends a
   chunk per generated fragment, in the shape the model behind the id uses.
-- A serialized Bedrock request is refused. Bedrock speaks REST-JSON, and the wire path answers only
-  the AWS JSON protocol services. A function bundling its own SDK reaches Bedrock through module
-  interception. S3 and every other non-JSON-protocol service are reached the same way.
+- Serialized Bedrock requests are unsupported. Use SDK interception.
 - The Bedrock control plane is unsimulated. `ListFoundationModels`, guardrail management, inference
   profile management and provisioned throughput all belong to `BedrockClient`.
 - Bedrock Agents and knowledge bases are unsimulated. `InvokeAgent`, `Retrieve` and
@@ -329,22 +317,20 @@ simSdk.restoreAll();
 - `ApplyGuardrail` is unsimulated, and a `guardrailConfig` or a `guardrailIdentifier` on an
   invocation is refused outright. Answering without the guardrail would make one look applied here
   and be applied in production.
-- `system`, `inferenceConfig`, `toolConfig` and `additionalModelRequestFields` are accepted and
-  decide nothing. `maxTokens` truncates no declared response, and a `toolConfig` naming no tools
+- `system`, `inferenceConfig`, `toolConfig` and `additionalModelRequestFields` are accepted and have
+  no effect. `maxTokens` truncates no declared response, and a `toolConfig` naming no tools
   still gets a declared tool call.
 - Token counts are fixed unless the declaration carries them. Counting them needs the tokenizer of
   the model the request names. Declare a `usage` where the code under test meters spend.
 - `metrics.latencyMs` is always zero. No time passes during an invocation.
 - A `Converse` with no messages is refused. Real Bedrock accepts one where the `modelId` names a
   prompt version from Prompt management, which is unsimulated.
-- The model id goes unchecked. AWS publishes no enumerable table of model ids, so refusing one would
-  be failing closed against Yulin's own gaps.
+- Any model ID is accepted.
 - `InvokeModel` has no built-in default response body, and an invocation matching a rule that
   declares none is refused. A response body is model-specific, and one family's shape served for
   every other one would parse into something the caller cannot read.
-- An `InvokeModel` body that arrives as a stream or a Blob matches no prompt rule. Reading it would
-  consume the caller's own request body, so such a request falls through to a model rule or to the
-  default.
-- A `Converse` call matching a response declared only as a body is refused for the same reason. It
-  does not fall back to the default.
+- An `InvokeModel` body supplied as a stream or `Blob` cannot match a prompt rule. It may still match
+  a model or default rule.
+- A `Converse` call matching a response declared only as a body is refused for the same reason. The
+  matching rule prevents the default rule from being selected.
 - There are no CloudFormation resource types for Bedrock, and Bedrock is absent from `serveSimAws`.