@intentius/chant-lexicon-aws 0.45.0 → 0.49.0

package/dist/rules/waw061.ts

@@ -0,0 +1,67 @@
+/**
+ * WAW061: Subnet CIDR Not Contained In VPC CIDR
+ *
+ * A subnet's CidrBlock must fall entirely inside its VPC's CidrBlock.
+ * Stock CDK does not check this — CloudFormation accepts the template and
+ * only fails the `AWS::EC2::Subnet` resource at deploy time
+ * ("The CIDR ... is invalid" / "does not fall within the CIDR range of the
+ * VPC"), after the rest of the stack may have already started rolling out.
+ * This is a cheap static graph check: follow the subnet's VpcId Ref to a
+ * declared VPC in the same template and do IPv4 CIDR-range math.
+ *
+ * Stays quiet whenever the graph can't prove it: intrinsic CIDR blocks,
+ * IPv6, a VpcId that isn't a simple Ref to a declared AWS::EC2::VPC, or a
+ * VPC whose own CidrBlock isn't a literal string.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, findResourceRefs, ipv4CidrContains } from "./cf-refs";
+
+export function checkSubnetCidrContainment(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::EC2::Subnet") continue;
+
+      const props = resource.Properties ?? {};
+      const subnetCidr = props.CidrBlock;
+      if (typeof subnetCidr !== "string") continue;
+
+      const vpcRefs = findResourceRefs(props.VpcId);
+      if (vpcRefs.size !== 1) continue;
+      const [vpcId] = vpcRefs;
+
+      const vpc = template.Resources[vpcId];
+      if (!vpc || vpc.Type !== "AWS::EC2::VPC") continue;
+
+      const vpcCidr = vpc.Properties?.CidrBlock;
+      if (typeof vpcCidr !== "string") continue;
+
+      const contained = ipv4CidrContains(vpcCidr, subnetCidr);
+      if (contained === false) {
+        diagnostics.push({
+          checkId: "WAW061",
+          severity: "error",
+          message: `Subnet "${logicalId}" CidrBlock ${subnetCidr} is not contained within VPC "${vpcId}"'s CidrBlock ${vpcCidr} — CloudFormation rejects this at deploy time`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw061: PostSynthCheck = {
+  id: "WAW061",
+  description: "Subnet CidrBlock falls outside its VPC's CidrBlock — fails at deploy time",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkSubnetCidrContainment(ctx);
+  },
+};

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA0YlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAoE3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiflG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA4E3B,CAAC"}

package/dist/skills/chant-aws-carve-terraform.md

@@ -1,6 +1,6 @@
 ---
 skill: chant-aws-carve-terraform
-description: Demo carving a resource out of Terraform into native chant — advise, emit, bridge, apply — fully offline
+description: Demo carving a resource out of Terraform into native chant — advise, emit, audit, bridge, apply — fully offline
 user-invocable: true
 ---
 
@@ -15,7 +15,7 @@ graduation.
 ## When to use
 
 - Someone asks "how does chant move things off Terraform?"
-- You want to show the advise → emit → bridge → apply loop end to end.
+- You want to show the advise → emit → audit → bridge → apply loop end to end.
 - You are evaluating whether a Terraform estate is worth carving.
 
 ## Preconditions
@@ -27,7 +27,7 @@ graduation.
 ## The fastest path: run the bundled demo
 
 The `examples/terraform-carve-out` example ships a runnable estate + state and a
-script that runs all four steps with commentary:
+script that runs all five steps with commentary:
 
 ```bash
 cd examples/terraform-carve-out
@@ -54,28 +54,30 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
      --state ./terraform/terraform.tfstate --output ./carveout
    ```
    Show `./carveout/src/assets.ts` — a real `new Bucket({ BucketName, Tags })` with
-   CloudFormation-style properties mapped from the Terraform state attributes.
-   Emit also scaffolds `./carveout` into a buildable chant project
-   (`chant.config.ts`, `package.json`), so `npm install && npm run build` works
-   there as-is. Explain: a Terraform-managed resource is not in any
-   CloudFormation stack, so the correct source of its live shape is the state
-   file, not a cloud read.
-
-3. **Lint the inherited resource — optional, offer it.**
+   CloudFormation-style properties mapped from the Terraform state attributes,
+   and the `aws_s3_bucket_versioning` sub-resource folded into
+   `VersioningConfiguration`. Emit also scaffolds `./carveout` into a buildable
+   chant project (`chant.config.ts`, `package.json`) and persists a carve
+   manifest (`*.carve.json`) — bridge and apply read the target from it, so
+   `--select` is only needed once. Explain: a Terraform-managed resource is not
+   in any CloudFormation stack, so the correct source of its live shape is the
+   state file, not a cloud read.
+
+3. **Audit the inherited resource.**
    ```bash
-   chant lint ./carveout/src --lexicon aws
+   chant build ./carveout/src --lexicon aws
    ```
-   After emit, offer to lint the carved source. chant audits the resource you
-   inherited from Terraform against the AWS lexicon's rules. Findings have a
-   severity: `error` (must fix before `chant build` will emit — e.g. an S3
-   bucket with no public-access block) and `warning`/`info` (advisory — e.g.
-   DynamoDB point-in-time recovery). This is a feature of carving: chant
-   immediately tells the person what is wrong with what they adopted. Whether to
-   fix an advisory finding is their call; errors block the build until resolved.
+   The first build fails, deliberately: the post-synth audit refuses the
+   adopted bucket because Terraform managed it without a public-access block or
+   a TLS-only policy. This is a feature of carving: chant immediately tells the
+   person what is wrong with what they adopted. Show the fix (add
+   `PublicAccessBlockConfiguration` and a companion `S3BucketPolicy` with an
+   `aws:SecureTransport = false` Deny — the tutorial page has the exact code),
+   then re-run the build and show the valid CloudFormation template.
 
 4. **Bridge — patch the surviving Terraform.**
    ```bash
-   chant carve bridge --from ./terraform --select aws_s3_bucket.assets --output ./carveout
+   chant carve bridge --from ./terraform --output ./carveout
    ```
    Show the generated `data "aws_s3_bucket" "assets"` and the rewired survivor.
    Emphasize it is dry-run: nothing in `./terraform` changed. `--apply-rewrites`
@@ -83,11 +85,12 @@ From `examples/terraform-carve-out`, with `TF=./terraform`:
 
 5. **Apply — graduation plan.**
    ```bash
-   chant carve apply --from ./terraform --select aws_s3_bucket.assets --env prod --stack assets
+   chant carve apply --from ./terraform --output ./carveout --env prod --stack assets
    ```
    Show the ownership marker (`chant:managed-by/stack/env`) and the finalized
-   runbook. Stress this makes no cloud call — the apply is the person's own
-   lifecycle; chant just plans it.
+   runbook. `--write-source` additionally stamps the marker tags into the
+   emitted source. Stress this makes no cloud call — the apply is the person's
+   own lifecycle; chant just plans it.
 
 ## Key points to land
 

package/dist/teardown.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Env teardown for the aws lexicon (chant #1222) — both halves of the
+ * `teardownOwned` / `executeTeardown` capability pair, at STACK granularity.
+ *
+ * Per-resource selection is impossible here by construction: the thin read
+ * (`describeResources`) is sourced from `describe-stack-resources`, which
+ * returns no tags, so no resource-level marker can be read on the teardown
+ * path. The stack is aws's ownership boundary anyway — the applier deploys
+ * whole stacks and deletes ride CloudFormation — so teardown enumerates the
+ * environment's stacks and verifies the marker on each STACK's own tags
+ * (`DescribeStacks` → `Tags`), stamped there by the apply paths from the
+ * template's `Metadata["chant:ownership"]` block.
+ *
+ * Which stacks are the environment's: the project's declared `stacks[]` when
+ * it is a multi-stack project, else the single-stack convention — the explicit
+ * `stack` option, else the stack named after the environment (the same rule
+ * `describeResources` and `exportResources` apply, see chant #932).
+ *
+ * Verification is tag-reading, never name-trusting. A resolved stack whose
+ * tags carry exactly the requested identity (managed-by + stack + env) is a
+ * candidate of type `AWS::CloudFormation::Stack`. A stack carrying a DIFFERENT
+ * marker identity verifiably belongs to another project or env — out of scope,
+ * silently, the way another env's resources are. A stack carrying NO marker at
+ * all is unknowable — a legacy chant stack from before stack tagging, or a
+ * foreign stack that happens to hold the env's name — and is reported as a
+ * hole (`filtered` / unverified-ownership), never deleted. An absent stack is
+ * knowledge, not a hole: nothing to tear down.
+ *
+ * Execution re-reads each candidate stack's tags immediately before deleting
+ * (the enumeration is a moment old at best, and a delete is not undoable),
+ * then rides the existing Query-API delete — `awsDelete`, DeleteStack polled
+ * to DELETE_COMPLETE. An identity that no longer matches is `not-prunable:
+ * unverified-ownership`; an already-absent stack is `deleted` (teardown is
+ * idempotent).
+ */
+import type { TeardownCandidate, TeardownEnumeration, TeardownExecution } from "@intentius/chant/lexicon";
+import { type OwnershipMarker } from "@intentius/chant/ownership";
+import { type AwsReadClientOptions } from "./api/read-client.js";
+import { type AwsHttp } from "./op/activities/aws-apply.js";
+/** The one candidate type this lexicon's teardown produces: whole stacks. */
+export declare const STACK_TYPE = "AWS::CloudFormation::Stack";
+export interface AwsTeardownOptions {
+    environment: string;
+    /** The identity to select on: this project's ownership stack + the env being torn down. */
+    marker: OwnershipMarker;
+    /** Explicit deployed stack name (single-stack override). */
+    stack?: string;
+    /** Region that stack is deployed in. */
+    region?: string;
+    /** A multi-stack project's declared stacks (chant.config `stacks[]`). */
+    stacks?: Array<{
+        name: string;
+        region?: string;
+    }>;
+}
+/** Injectable transports/timeouts, so tests double the Query API (no network). */
+export interface AwsTeardownDeps {
+    /** Options for the read client's `DescribeStacks` calls (http injection, endpoint). */
+    read?: AwsReadClientOptions;
+    /** The applier transport `awsDelete` polls DeleteStack through. */
+    applyHttp?: AwsHttp;
+    /** DeleteStack settle timeout in ms (default `awsDelete`'s 300000). */
+    timeoutMs?: number;
+    /** DeleteStack poll interval in ms (default `awsDelete`'s 3000). */
+    intervalMs?: number;
+}
+/** The stacks an env teardown resolves to: `stacks[]`, else the single-stack convention. */
+export declare function resolveTeardownStacks(options: AwsTeardownOptions): Array<{
+    name: string;
+    region?: string;
+}>;
+/**
+ * Enumerate the environment's marker-verified stacks — the aws half of
+ * `chant lifecycle teardown <env>` planning. Read-only.
+ */
+export declare function teardownOwned(options: AwsTeardownOptions, deps?: AwsTeardownDeps): Promise<TeardownEnumeration>;
+/**
+ * Delete the handed-over stacks: re-verify each stack's own tags, then
+ * DeleteStack via `awsDelete`, polled to DELETE_COMPLETE. One outcome per
+ * candidate, always.
+ */
+export declare function executeTeardown(options: AwsTeardownOptions & {
+    candidates: TeardownCandidate[];
+}, deps?: AwsTeardownDeps): Promise<TeardownExecution>;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/teardown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teardown.d.ts","sourceRoot":"","sources":["../src/teardown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EAGlB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAEjF,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,MAAM,EAAE,eAAe,CAAC;IACxB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnD;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4FAA4F;AAC5F,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,GAC1B,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ1C;AAmDD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAuD9B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAAG;IAAE,UAAU,EAAE,iBAAiB,EAAE,CAAA;CAAE,EACjE,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAW5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.45.0",
+  "version": "0.49.0",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -73,14 +73,14 @@
   },
   "dependencies": {
     "fflate": "^0.8.2",
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.3.1"
   },
   "devDependencies": {
     "@intentius/chant": "*",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.45.0",
+    "@intentius/chant": "^0.49.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/read-client.test.ts

@@ -198,6 +198,15 @@ describe("Cloud Control", () => {
     expect(await listResources("AWS::S3::Bucket", { http })).toEqual([]);
   });
 
+  test("listResources scopes a child listing with ResourceModel, JSON-encoded as the API takes it", async () => {
+    const { http, calls } = recording(() => respond(JSON.stringify({ ResourceDescriptions: [] })));
+    await listResources("AWS::IAM::RolePolicy", { http }, { RoleName: "app-role" });
+    expect(JSON.parse(calls[0].body)).toEqual({
+      TypeName: "AWS::IAM::RolePolicy",
+      ResourceModel: JSON.stringify({ RoleName: "app-role" }),
+    });
+  });
+
   test("parseResourceDescription refuses anything that is not a model object", () => {
     expect(parseResourceDescription(null)).toBeNull();
     expect(parseResourceDescription({ Identifier: "a" })).toBeNull();

package/src/api/read-client.ts

@@ -434,17 +434,30 @@ export async function getResource(
   return parseResourceDescription(body.ResourceDescription);
 }
 
-/** `ListResources` — every live resource of one type, paginated to exhaustion. */
+/**
+ * `ListResources` — every live resource of one type, paginated to exhaustion.
+ *
+ * `resourceModel` is Cloud Control's `ResourceModel`: the scope a child-typed
+ * listing requires (`{ RoleName }` for `AWS::IAM::RolePolicy`,
+ * `{ TopicArn }` for `AWS::SNS::Subscription`). The API takes it as a JSON
+ * *string*, the same double encoding `GetResource` answers with; this takes
+ * the object and encodes it so no caller repeats that detail.
+ */
 export async function listResources(
   typeName: string,
   options: AwsReadClientOptions = {},
+  resourceModel?: Record<string, unknown>,
 ): Promise<CloudControlDescription[]> {
   const out: CloudControlDescription[] = [];
   let nextToken: string | undefined;
   do {
     const body = await cloudControl(
       "ListResources",
-      { TypeName: typeName, ...(nextToken ? { NextToken: nextToken } : {}) },
+      {
+        TypeName: typeName,
+        ...(resourceModel ? { ResourceModel: JSON.stringify(resourceModel) } : {}),
+        ...(nextToken ? { NextToken: nextToken } : {}),
+      },
       options,
     );
     const descriptions = Array.isArray(body.ResourceDescriptions) ? body.ResourceDescriptions : [];

package/src/components/cloud-executor.ts

@@ -24,6 +24,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { realDocker, type DockerClient } from "@intentius/chant/components/verbs/cloud-executor";
 import { q } from "@intentius/chant/components/verbs/process-runner";
+import { ownershipStackTagsForBody } from "../ownership.js";
 
 export type { DockerClient };
 
@@ -432,10 +433,18 @@ const realCloudFormation: CloudFormationClient = {
       body = readFileSync(args.templatePath, "utf8");
     } catch { /* unreadable template — create-change-set reports it */ }
     const capabilities = awsDeployCapabilitiesForBody(body).join(" ");
+    // The template's ownership marker becomes the STACK's own tags (#1222) —
+    // the identity stack-level teardown verifies before a DeleteStack. Same
+    // source as the applier's `Tags.member.N`: `Metadata["chant:ownership"]`.
+    const stackTags = Object.entries(ownershipStackTagsForBody(body))
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => q(`Key=${k},Value=${v}`))
+      .join(" ");
+    const tagsFlag = stackTags ? ` --tags ${stackTags}` : "";
     await run(
       `aws cloudformation create-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)} ` +
         `--change-set-type ${changeSetType} ` +
-        `--template-body file://${args.templatePath} --capabilities ${capabilities}${paramFlag}`,
+        `--template-body file://${args.templatePath} --capabilities ${capabilities}${paramFlag}${tagsFlag}`,
     );
     await run(
       `aws cloudformation wait change-set-create-complete --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)}`,

package/src/composites/agentcore-agent.ts

@@ -45,19 +45,36 @@ export function agentCoreDefaultEndpointArn(runtime: InstanceType<typeof Runtime
 }
 
 /**
- * AgentCore's `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName`
- * fields are all bound to the CFN registry pattern
- * `^[a-zA-Z][a-zA-Z0-9_]{0,47}$` (spot-checked against the CloudFormation
- * schema for #882 — no hyphens, unlike chant's usual kebab-case component
- * names). `Gateway`/`GatewayTarget`/`WorkloadIdentity` names accept hyphens,
- * so only the Runtime family needs sanitizing. Non-identifier characters
- * become `_`, and a leading digit/underscore gets an `A` prefix so the result
- * always starts with a letter.
+ * Bedrock AgentCore's real limits, verified against the CloudFormation
+ * registry schema for `AWS::BedrockAgentCore::{Runtime,RuntimeEndpoint,Memory}`
+ * (#882).
+ *
+ * Exported for the same reason as `MICROVM_LIMITS` (#1374, #1420): a
+ * consumer driving AgentCore through another control plane needs the same
+ * numbers, and copying them is how two sources of truth start.
+ */
+export const AGENTCORE_LIMITS = {
+  /**
+   * `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName` fields
+   * are bound to this pattern — no hyphens, unlike chant's usual kebab-case
+   * component names. `Gateway`/`GatewayTarget`/`WorkloadIdentity` names
+   * accept hyphens, so only the Runtime family needs sanitizing.
+   */
+  runtimeNamePattern: /^[a-zA-Z][a-zA-Z0-9_]{0,47}$/,
+  maxRuntimeNameLength: 48,
+  /** `Memory` event retention bounds, in days. */
+  memoryEventExpiryDays: { min: 3, max: 365, default: 30 },
+} as const;
+
+/**
+ * Non-identifier characters become `_`, and a leading digit/underscore gets
+ * an `A` prefix so the result always starts with a letter — then truncated
+ * to {@link AGENTCORE_LIMITS}'s `maxRuntimeNameLength`.
  */
 function toRuntimeIdentifier(name: string): string {
   const cleaned = name.replace(/[^a-zA-Z0-9_]/g, "_");
   const identifier = /^[a-zA-Z]/.test(cleaned) ? cleaned : `A${cleaned}`;
-  return identifier.slice(0, 48);
+  return identifier.slice(0, AGENTCORE_LIMITS.maxRuntimeNameLength);
 }
 
 /**
@@ -117,7 +134,7 @@ export interface AgentCoreAgentProps {
    * managed one and fails on a real apply (#978, see the composite doc).
    */
   endpointName?: string;
-  /** Memory event retention, in days. CFN bounds: 3-365. Default: 30. */
+  /** Memory event retention, in days. Bounds: {@link AGENTCORE_LIMITS.memoryEventExpiryDays}. */
   memoryEventExpiryDays?: number;
   /** Gateway authorizer. Mirrors the generated `BedrockAgentCoreGateway_AuthorizerType` CFN enum. Default: "AWS_IAM". */
   gatewayAuthorizerType?: "CUSTOM_JWT" | "AWS_IAM" | "NONE" | "AUTHENTICATE_ONLY";
@@ -194,9 +211,14 @@ export const AgentCoreAgent = Composite<AgentCoreAgentProps, AgentCoreAgentResul
   if (networkMode === "VPC" && (props.vpcSubnetIds === undefined || props.vpcSecurityGroupIds === undefined)) {
     throw new Error("AgentCoreAgent requires vpcSubnetIds and vpcSecurityGroupIds when networkMode is \"VPC\"");
   }
-  const memoryEventExpiryDays = props.memoryEventExpiryDays ?? 30;
-  if (memoryEventExpiryDays < 3 || memoryEventExpiryDays > 365) {
-    throw new Error("AgentCoreAgent memoryEventExpiryDays must be between 3 and 365");
+  const memoryEventExpiryDays = props.memoryEventExpiryDays ?? AGENTCORE_LIMITS.memoryEventExpiryDays.default;
+  if (
+    memoryEventExpiryDays < AGENTCORE_LIMITS.memoryEventExpiryDays.min ||
+    memoryEventExpiryDays > AGENTCORE_LIMITS.memoryEventExpiryDays.max
+  ) {
+    throw new Error(
+      `AgentCoreAgent memoryEventExpiryDays must be between ${AGENTCORE_LIMITS.memoryEventExpiryDays.min} and ${AGENTCORE_LIMITS.memoryEventExpiryDays.max}`,
+    );
   }
 
   const runtimeName = toRuntimeIdentifier(props.name);

package/src/composites/bucket-deployment.test.ts

@@ -0,0 +1,84 @@
+import { describe, test, expect } from "vitest";
+import { BucketDeployment } from "./bucket-deployment";
+
+describe("BucketDeployment", () => {
+  test("private-by-default: encrypted, public access fully blocked, retained on delete, no policy member", () => {
+    const c = BucketDeployment({});
+    expect(c.bucket).toBeDefined();
+    expect((c as unknown as Record<string, unknown>).bucketPolicy).toBeUndefined();
+
+    const props = (c.bucket as any).props;
+    expect(props.BucketEncryption.props.ServerSideEncryptionConfiguration).toHaveLength(1);
+    expect(props.PublicAccessBlockConfiguration.props).toEqual({
+      BlockPublicAcls: true,
+      BlockPublicPolicy: true,
+      IgnorePublicAcls: true,
+      RestrictPublicBuckets: true,
+    });
+    expect(props.VersioningConfiguration).toBeUndefined();
+    expect(props.WebsiteConfiguration).toBeUndefined();
+
+    const attrs = (c.bucket as any).attributes;
+    expect(attrs.DeletionPolicy).toBe("Retain");
+  });
+
+  test("bucketName threads through, versioning enables Status: Enabled", () => {
+    const c = BucketDeployment({ bucketName: "my-content-bucket", versioned: true });
+    const props = (c.bucket as any).props;
+    expect(props.BucketName).toBe("my-content-bucket");
+    expect(props.VersioningConfiguration.props).toEqual({ Status: "Enabled" });
+  });
+
+  test("removalPolicy: destroy maps to DeletionPolicy: Delete", () => {
+    const c = BucketDeployment({ removalPolicy: "destroy" });
+    expect((c.bucket as any).attributes.DeletionPolicy).toBe("Delete");
+  });
+
+  test("website shape: opens the public-access block, sets WebsiteConfiguration, and attaches a scoped public-read bucketPolicy", () => {
+    const c = BucketDeployment({
+      website: { indexDocument: "index.html", errorDocument: "error.html" },
+    }) as unknown as { bucket: any; bucketPolicy: any };
+
+    const bucketProps = c.bucket.props;
+    expect(bucketProps.PublicAccessBlockConfiguration.props).toEqual({
+      BlockPublicAcls: false,
+      BlockPublicPolicy: false,
+      IgnorePublicAcls: false,
+      RestrictPublicBuckets: false,
+    });
+    expect(bucketProps.WebsiteConfiguration.props).toEqual({
+      IndexDocument: "index.html",
+      ErrorDocument: "error.html",
+    });
+
+    expect(c.bucketPolicy).toBeDefined();
+    expect(c.bucketPolicy.props.Bucket).toBe(c.bucket); // bucket.Ref is the resource instance itself
+    const statement = c.bucketPolicy.props.PolicyDocument.Statement[0];
+    expect(statement).toEqual({ Effect: "Allow", Principal: "*", Action: "s3:GetObject", Resource: expect.anything() });
+  });
+
+  test("website without errorDocument omits it rather than writing undefined", () => {
+    const c = BucketDeployment({ website: { indexDocument: "index.html" } });
+    const websiteProps = (c.bucket as any).props.WebsiteConfiguration.props;
+    expect(websiteProps).toEqual({ IndexDocument: "index.html" });
+    expect("ErrorDocument" in websiteProps).toBe(false);
+  });
+
+  test("tags pass straight through to the bucket", () => {
+    const c = BucketDeployment({ tags: [{ Key: "env", Value: "prod" }] });
+    expect((c.bucket as any).props.Tags).toEqual([{ Key: "env", Value: "prod" }]);
+  });
+
+  test("defaults escape hatch reaches the bucket (e.g. object-lock)", () => {
+    const c = BucketDeployment({ defaults: { bucket: { ObjectLockEnabled: true } } });
+    expect((c.bucket as any).props.ObjectLockEnabled).toBe(true);
+  });
+
+  test("defaults escape hatch reaches the bucket policy", () => {
+    const c = BucketDeployment({
+      website: { indexDocument: "index.html" },
+      defaults: { bucketPolicy: { Bucket: "explicit-bucket-name" } },
+    }) as unknown as { bucketPolicy: any };
+    expect(c.bucketPolicy.props.Bucket).toBe("explicit-bucket-name");
+  });
+});