@intentius/chant-lexicon-aws 0.44.13 → 0.45.0

package/src/components/capability-plugin.ts

@@ -69,8 +69,11 @@ export const awsCapabilityPlugin: CapabilityPlugin = {
   name: "aws",
   // The lexicon package's own version (#1505) — the "1.0.0" this shipped with
   // was the starter plugin's literal, copied along in the #681 extraction and
-  // never a real package version.
-  version: ownPackageVersion(import.meta.url),
+  // never a real package version. A getter, so the package.json read happens
+  // on first access rather than at import time.
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
   capabilities: awsCapabilities,
   families: () => AWS_VERB_FAMILIES,
 };

package/src/components/cloud-executor.test.ts

@@ -1,5 +1,13 @@
 import { describe, test, expect } from "vitest";
-import { applyAwsEndpoint, applyAwsEndpointArgv, awsDeployCapabilities, ecsDeploymentId, ecsServiceStable } from "./cloud-executor";
+import {
+  applyAwsEndpoint,
+  applyAwsEndpointArgv,
+  awsDeployCapabilities,
+  awsDeployCapabilitiesForBody,
+  awsDeployCapabilityList,
+  ecsDeploymentId,
+  ecsServiceStable,
+} from "./cloud-executor";
 
 describe("ecsDeploymentId / ecsServiceStable — tolerate Floci's missing deployments (#937)", () => {
   test("deployment id: real AWS shape", () => {
@@ -74,4 +82,24 @@ describe("awsDeployCapabilities — CAPABILITY_AUTO_EXPAND for Transform macros"
     );
     expect(awsDeployCapabilities({ Transform: ["AWS::LanguageExtensions"] })).toContain("CAPABILITY_AUTO_EXPAND");
   });
+  test("list form mirrors the string form", () => {
+    expect(awsDeployCapabilityList({})).toEqual(["CAPABILITY_NAMED_IAM"]);
+    expect(awsDeployCapabilityList({ Transform: "AWS::Serverless-2016-10-31" })).toEqual([
+      "CAPABILITY_NAMED_IAM",
+      "CAPABILITY_AUTO_EXPAND",
+    ]);
+    expect(awsDeployCapabilityList({ Transform: ["AWS::LanguageExtensions", "AWS::Serverless-2016-10-31"] })).toEqual([
+      "CAPABILITY_NAMED_IAM",
+      "CAPABILITY_AUTO_EXPAND",
+    ]);
+  });
+  test("raw body: parses JSON, falls back to NAMED_IAM for non-JSON or empty input", () => {
+    expect(awsDeployCapabilitiesForBody(JSON.stringify({ Transform: "AWS::SecretsManager-2020-07-23", Resources: {} }))).toEqual([
+      "CAPABILITY_NAMED_IAM",
+      "CAPABILITY_AUTO_EXPAND",
+    ]);
+    expect(awsDeployCapabilitiesForBody(JSON.stringify({ Resources: {} }))).toEqual(["CAPABILITY_NAMED_IAM"]);
+    expect(awsDeployCapabilitiesForBody("Resources:\n  B:\n    Type: AWS::S3::Bucket\n")).toEqual(["CAPABILITY_NAMED_IAM"]);
+    expect(awsDeployCapabilitiesForBody("")).toEqual(["CAPABILITY_NAMED_IAM"]);
+  });
 });

package/src/components/cloud-executor.ts

@@ -393,9 +393,26 @@ async function cfnChangeSetType(stackName: string): Promise<"CREATE" | "UPDATE">
  * CloudFormation refuses without the acknowledgement.
  */
 export function awsDeployCapabilities(template: { Transform?: unknown }): string {
+  return awsDeployCapabilityList(template).join(" ");
+}
+
+/** {@link awsDeployCapabilities} as a list, for the CFN API's `Capabilities.member.N` params. */
+export function awsDeployCapabilityList(template: { Transform?: unknown }): string[] {
   return template.Transform !== undefined
-    ? "CAPABILITY_NAMED_IAM CAPABILITY_AUTO_EXPAND"
-    : "CAPABILITY_NAMED_IAM";
+    ? ["CAPABILITY_NAMED_IAM", "CAPABILITY_AUTO_EXPAND"]
+    : ["CAPABILITY_NAMED_IAM"];
+}
+
+/**
+ * {@link awsDeployCapabilityList} for a raw template body. A body that isn't
+ * JSON gets the default list; the deploy itself reports the real problem.
+ */
+export function awsDeployCapabilitiesForBody(body: string): string[] {
+  try {
+    return awsDeployCapabilityList(JSON.parse(body) as { Transform?: unknown });
+  } catch {
+    return ["CAPABILITY_NAMED_IAM"];
+  }
 }
 
 const realCloudFormation: CloudFormationClient = {
@@ -410,10 +427,11 @@ const realCloudFormation: CloudFormationClient = {
     // for one still in REVIEW_IN_PROGRESS (a prior CREATE change set never
     // executed), mirroring what `aws cloudformation deploy` does under the hood.
     const changeSetType = await cfnChangeSetType(args.stackName);
-    let capabilities = "CAPABILITY_NAMED_IAM";
+    let body = "";
     try {
-      capabilities = awsDeployCapabilities(JSON.parse(readFileSync(args.templatePath, "utf8")) as { Transform?: unknown });
-    } catch { /* unreadable/non-JSON template — keep the default capability */ }
+      body = readFileSync(args.templatePath, "utf8");
+    } catch { /* unreadable template — create-change-set reports it */ }
+    const capabilities = awsDeployCapabilitiesForBody(body).join(" ");
     await run(
       `aws cloudformation create-change-set --stack-name ${q(args.stackName)} --change-set-name ${q(changeSetName)} ` +
         `--change-set-type ${changeSetType} ` +

package/src/composites/agentcore-agent.test.ts

@@ -6,7 +6,7 @@ import { AttrRef } from "@intentius/chant/attrref";
 // reaching into core directly here mirrors nested-stack-integration.test.ts's
 // precedent for aws-lexicon integration-style tests.
 import { resolveAttrRefs } from "../../../../packages/core/src/discovery/resolve";
-import { AgentCoreAgent } from "./agentcore-agent";
+import { AgentCoreAgent, agentCoreDefaultEndpointArn } from "./agentcore-agent";
 import { Split, Ref } from "../intrinsics";
 import { awsSerializer } from "../serializer";
 
@@ -15,12 +15,12 @@ const baseProps = {
   containerUri: "123456789012.dkr.ecr.us-east-1.amazonaws.com/support-agent:latest",
 };
 
-// The endpoint is opt-in (#978) — it races the Runtime's async version-READY when
-// created in the same apply. Tests that exercise the endpoint pass this variant.
-const withEndpoint = { ...baseProps, provisionEndpoint: true };
+// An explicit endpoint exists only for a non-DEFAULT alias (#978): AgentCore owns DEFAULT,
+// and declaring it races the Runtime's async version-READY. Endpoint tests use this variant.
+const withEndpoint = { ...baseProps, endpointName: "PROD" };
 
 describe("AgentCoreAgent", () => {
-  test("returns 7 members by default; the endpoint is opt-in (#978)", () => {
+  test("returns 7 members by default; no RuntimeEndpoint (#978)", () => {
     const instance = AgentCoreAgent(baseProps);
     expect(Object.keys(instance.members)).toEqual([
       "role", "gatewayRole", "runtime", "memory",
@@ -29,7 +29,7 @@ describe("AgentCoreAgent", () => {
     expect((instance as any).endpoint).toBeUndefined();
   });
 
-  test("provisionEndpoint adds the endpoint as an 8th member", () => {
+  test("endpointName adds an explicit endpoint as an 8th member", () => {
     const instance = AgentCoreAgent(withEndpoint);
     expect(Object.keys(instance.members)).toContain("endpoint");
     expect(Object.keys(instance.members)).toHaveLength(8);
@@ -40,13 +40,13 @@ describe("AgentCoreAgent", () => {
     expect(expanded.has("agentRole")).toBe(true);
     expect(expanded.has("agentGatewayRole")).toBe(true);
     expect(expanded.has("agentRuntime")).toBe(true);
-    expect(expanded.has("agentEndpoint")).toBe(false); // opt-in (#978)
+    expect(expanded.has("agentEndpoint")).toBe(false); // managed DEFAULT, not declared (#978)
     expect(expanded.has("agentMemory")).toBe(true);
     expect(expanded.has("agentWorkloadIdentity")).toBe(true);
     expect(expanded.has("agentGateway")).toBe(true);
     expect(expanded.has("agentGatewayTarget")).toBe(true);
     expect(expanded.size).toBe(7);
-    // With the endpoint opted in, it appears as agentEndpoint.
+    // With an explicit non-DEFAULT endpoint, it appears as agentEndpoint.
     expect(expandComposite("agent", AgentCoreAgent(withEndpoint)).has("agentEndpoint")).toBe(true);
   });
 
@@ -69,7 +69,7 @@ describe("AgentCoreAgent", () => {
     const memoryProps = (instance.memory as any).props;
     expect(runtimeProps.AgentRuntimeName).toBe("support_agent");
     expect(runtimeProps.AgentRuntimeName).toMatch(/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/);
-    expect(endpointProps.Name).toBe("DEFAULT");
+    expect(endpointProps.Name).toBe("PROD");
     expect(memoryProps.Name).toBe("support_agentMemory");
     expect(memoryProps.Name).toMatch(/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/);
   });
@@ -144,7 +144,7 @@ describe("AgentCoreAgent", () => {
       code: { s3Bucket: "loom-artifacts", s3Prefix: "agents/assistant.zip", runtime: "PYTHON_3_12", entryPoint: ["app.py"] },
     }));
     resolveAttrRefs(expanded);
-    const template = JSON.parse(awsSerializer.serialize(expanded));
+    const template = JSON.parse(awsSerializer.serialize(expanded) as string);
     const artifact = template.Resources.agentRuntime.Properties.AgentRuntimeArtifact;
     expect(artifact.ContainerConfiguration).toBeUndefined();
     expect(artifact.CodeConfiguration).toEqual({
@@ -195,7 +195,27 @@ describe("AgentCoreAgent", () => {
     );
   });
 
-  test("RuntimeEndpoint references runtime.AgentRuntimeId (when opted in)", () => {
+  test("endpointName \"DEFAULT\" is rejected — AgentCore provisions the managed DEFAULT endpoint (#978)", () => {
+    expect(() => AgentCoreAgent({ ...baseProps, endpointName: "DEFAULT" })).toThrow(
+      "AgentCoreAgent endpointName must not be \"DEFAULT\"",
+    );
+  });
+
+  test("explicit endpoint name is sanitized to the Runtime identifier pattern", () => {
+    const instance = AgentCoreAgent({ ...baseProps, endpointName: "blue-green" });
+    expect((instance.endpoint as any).props.Name).toBe("blue_green");
+  });
+
+  test("agentCoreDefaultEndpointArn derives the managed DEFAULT endpoint ARN from the Runtime ARN", () => {
+    const instance = AgentCoreAgent(baseProps);
+    const expanded = expandComposite("agent", instance);
+    resolveAttrRefs(expanded);
+    expect(JSON.parse(JSON.stringify(agentCoreDefaultEndpointArn(instance.runtime)))).toEqual({
+      "Fn::Sub": "${agentRuntime.AgentRuntimeArn}/runtime-endpoint/DEFAULT",
+    });
+  });
+
+  test("RuntimeEndpoint references runtime.AgentRuntimeId (when an explicit endpoint is named)", () => {
     const instance = AgentCoreAgent(withEndpoint);
     const endpointProps = (instance.endpoint as any).props;
     expect(endpointProps.AgentRuntimeId).toBeInstanceOf(AttrRef);
@@ -245,7 +265,7 @@ describe("AgentCoreAgent", () => {
   test("serializes to a valid CloudFormation template with the expected resource types", () => {
     const expanded = expandComposite("agent", AgentCoreAgent(withEndpoint));
     resolveAttrRefs(expanded);
-    const output = awsSerializer.serialize(expanded);
+    const output = awsSerializer.serialize(expanded) as string;
     const template = JSON.parse(output);
 
     expect(template.AWSTemplateFormatVersion).toBe("2010-09-09");

package/src/composites/agentcore-agent.ts

@@ -30,6 +30,19 @@ export type AgentManagedRuntime =
   | "PYTHON_3_13"
   | "PYTHON_3_14";
 import { agentCoreTrustPolicy } from "./agentcore-trust-policy";
+import { Sub, type SubIntrinsic } from "../intrinsics";
+
+/**
+ * ARN of the managed `DEFAULT` endpoint AgentCore provisions with a Runtime,
+ * as an `Fn::Sub` over the Runtime's ARN. No CloudFormation attribute carries
+ * it (the Runtime schema exposes only `AgentRuntimeArn`/`AgentRuntimeId`/
+ * `AgentRuntimeVersion`/`Status`), but the format is fixed by the
+ * CreateAgentRuntimeEndpoint API:
+ * `arn:aws:bedrock-agentcore:<region>:<account>:runtime/<id>/runtime-endpoint/<name>`.
+ */
+export function agentCoreDefaultEndpointArn(runtime: InstanceType<typeof Runtime>): SubIntrinsic {
+  return Sub`${runtime.AgentRuntimeArn}/runtime-endpoint/DEFAULT`;
+}
 
 /**
  * AgentCore's `Runtime`/`RuntimeEndpoint`/`Memory` `Name`/`AgentRuntimeName`
@@ -70,7 +83,7 @@ export interface AgentCoreCodeArtifact {
 export interface AgentCoreAgentProps {
   /**
    * Base name for the agent's resources. `toRuntimeIdentifier(name)` derives
-   * the Runtime/RuntimeEndpoint/Memory names; Gateway/GatewayTarget/
+   * the Runtime/Memory (and any explicit endpoint) names; Gateway/GatewayTarget/
    * WorkloadIdentity use `name` as-is (hyphens are valid there).
    */
   name: string;
@@ -94,20 +107,16 @@ export interface AgentCoreAgentProps {
   protocolConfiguration?: "A2A" | "AGUI" | "HTTP" | "MCP";
   /** Environment variables passed to the Runtime container. */
   environmentVariables?: Record<string, string>;
-  /** RuntimeEndpoint name — the alias a version-promotion capability would repoint (deferred, see #882). Default: "DEFAULT". */
-  endpointName?: string;
   /**
-   * Create the `RuntimeEndpoint` in this template. **Default: false.** A
-   * RuntimeEndpoint can only be created once the Runtime's agent *version* is
-   * READY, which is asynchronous and is NOT gated by the Runtime resource's own
-   * CloudFormation `CREATE_COMPLETE` — so creating the endpoint in the same apply
-   * as the Runtime races and fails on a real deploy ("Agent version 1 must be in
-   * READY status. Current status: CREATING", #978). Leave this off and create the
-   * endpoint out-of-band once the runtime is READY — which is what Bedrock
-   * AgentCore's own tooling (and Loom's app) does. Opt in only when you know the
-   * Runtime will already be READY (e.g. a version-promotion flow on an existing runtime).
+   * Name of an explicit, non-`DEFAULT` `RuntimeEndpoint` to create alongside
+   * the Runtime (e.g. `"PROD"`), the alias a version-promotion flow would
+   * later repoint (deferred, see #882). Omit it and no endpoint resource is
+   * created: AgentCore provisions a managed `DEFAULT` endpoint with every
+   * Runtime, and it tracks the latest version on its own. `"DEFAULT"` is
+   * rejected, since a CloudFormation endpoint of that name duplicates the
+   * managed one and fails on a real apply (#978, see the composite doc).
    */
-  provisionEndpoint?: boolean;
+  endpointName?: string;
   /** Memory event retention, in days. CFN bounds: 3-365. Default: 30. */
   memoryEventExpiryDays?: number;
   /** Gateway authorizer. Mirrors the generated `BedrockAgentCoreGateway_AuthorizerType` CFN enum. Default: "AWS_IAM". */
@@ -134,7 +143,7 @@ export type AgentCoreAgentResult = {
   role: InstanceType<typeof Role>;
   gatewayRole: InstanceType<typeof Role>;
   runtime: InstanceType<typeof Runtime>;
-  /** Present only when `provisionEndpoint` is set — see that prop (#978). */
+  /** Present only when `endpointName` names an explicit non-DEFAULT endpoint (#978). */
   endpoint?: InstanceType<typeof RuntimeEndpoint>;
   memory: InstanceType<typeof Memory>;
   workloadIdentity: InstanceType<typeof WorkloadIdentity>;
@@ -144,7 +153,7 @@ export type AgentCoreAgentResult = {
 
 /**
  * A Bedrock AgentCore agent as one CloudFormation-serializable bundle — the
- * composite/base path from #882: `Runtime` + `RuntimeEndpoint` + `Memory` +
+ * composite/base path from #882: `Runtime` + `Memory` +
  * `Gateway`/`GatewayTarget` + `WorkloadIdentity` + IAM, deployable with
  * `cfn-deploy` + `wait-for-stack` and no bespoke verb.
  *
@@ -156,10 +165,18 @@ export type AgentCoreAgentResult = {
  * for workflows (e.g. a future credential-provider capability) that need an
  * explicit workload identity of their own.
  *
- * The `agentcore-deploy` version-promotion capability that would repoint
- * `endpoint`'s `TargetVersion`/`LiveVersion` is deferred (GA-gated, #882) —
- * this composite only wires the CloudFormation shape it would eventually
- * apply against.
+ * There is no `RuntimeEndpoint` in the bundle by default. AgentCore creates a
+ * managed `DEFAULT` endpoint with every Runtime and repoints it at each new
+ * version on its own, so a CloudFormation `DEFAULT` endpoint is redundant. It
+ * is also the race that sank a live deploy (#978): the Runtime resource's
+ * `CREATE_COMPLETE` fires while AgentCore is still turning the artifact into
+ * a READY agent version, and the endpoint's CREATE then fails with "Agent
+ * version 1 must be in READY status". Invoking the Runtime with no qualifier
+ * hits the managed DEFAULT endpoint; {@link agentCoreDefaultEndpointArn}
+ * builds its ARN from the Runtime's. `endpointName` adds an explicit
+ * non-DEFAULT endpoint for the `agentcore-deploy` version-promotion flow,
+ * which is deferred (GA-gated, #882) — this composite only wires the
+ * CloudFormation shape it would eventually apply against.
  */
 export const AgentCoreAgent = Composite<AgentCoreAgentProps, AgentCoreAgentResult>((props) => {
   const { defaults } = props;
@@ -241,12 +258,15 @@ export const AgentCoreAgent = Composite<AgentCoreAgentProps, AgentCoreAgentResul
     EnvironmentVariables: props.environmentVariables,
   }, defaults?.runtime));
 
-  // Opt-in only (#978): the endpoint races the Runtime's async version-READY when
-  // created in the same apply. Off by default; create it out-of-band post-READY.
-  const endpoint = props.provisionEndpoint
+  // Explicit endpoints only for a non-DEFAULT alias (#978): AgentCore owns
+  // DEFAULT, and creating it here races the Runtime's async version-READY.
+  if (props.endpointName === "DEFAULT") {
+    throw new Error("AgentCoreAgent endpointName must not be \"DEFAULT\": AgentCore provisions the managed DEFAULT endpoint itself");
+  }
+  const endpoint = props.endpointName !== undefined
     ? new RuntimeEndpoint(mergeDefaults({
         AgentRuntimeId: runtime.AgentRuntimeId,
-        Name: toRuntimeIdentifier(props.endpointName ?? "DEFAULT"),
+        Name: toRuntimeIdentifier(props.endpointName),
       }, defaults?.endpoint))
     : undefined;
 

package/src/composites/index.ts

@@ -43,5 +43,5 @@ export { EksCluster } from "./eks-cluster";
 export type { EksClusterProps } from "./eks-cluster";
 export { MicrovmApp, MICROVM_LIMITS } from "./microvm-app";
 export type { MicrovmAppProps, MicrovmAppResult, MicrovmAppBuildConnectorProps, MicrovmMemoryMiB } from "./microvm-app";
-export { AgentCoreAgent } from "./agentcore-agent";
+export { AgentCoreAgent, agentCoreDefaultEndpointArn } from "./agentcore-agent";
 export type { AgentCoreAgentProps, AgentCoreAgentResult } from "./agentcore-agent";

package/src/composites/microvm-app.test.ts

@@ -149,7 +149,7 @@ describe("MicrovmApp", () => {
       const instance = MicrovmApp(baseProps);
       const entities = expandComposite("worker", instance);
       resolveAttrRefs(entities);
-      const output = awsSerializer.serialize(entities);
+      const output = awsSerializer.serialize(entities) as string;
       const template = JSON.parse(output);
 
       expect(template.AWSTemplateFormatVersion).toBe("2010-09-09");
@@ -204,7 +204,7 @@ describe("MicrovmApp", () => {
       });
       const entities = expandComposite("worker", instance);
       resolveAttrRefs(entities);
-      const output = awsSerializer.serialize(entities);
+      const output = awsSerializer.serialize(entities) as string;
       const template = JSON.parse(output);
 
       const connector = template.Resources.workerConnector;

package/src/deep-observe.test.ts

@@ -24,6 +24,7 @@ const {
   observeResourcesDeepAws,
   awsDeepNormalizationHooks,
   hasOwnershipMarker,
+  schemaReadOnlyPatterns,
 } = await import("./deep-observe");
 const { parseResourceDescription } = await import("./api/read-client");
 const { deepDiffForLexicon } = await import("@intentius/chant/lifecycle/deep-observe");
@@ -252,6 +253,99 @@ describe("the aws noise rules", () => {
   });
 });
 
+// A property the schema marks read-only is a GetAtt attribute, never a
+// declared input. The live read still reports it, so without the schema-driven
+// rule every clean apply shows `<undeclared> -> value` for it.
+describe("schema read-only properties are attributes, not drift (#1641)", () => {
+  test("the registry is read off the schema's readOnlyProperties, arrays spelled as patterns", () => {
+    expect([...schemaReadOnlyPatterns("AWS::IAM::ManagedPolicy")]).toEqual(
+      expect.arrayContaining(["PolicyArn", "PolicyId", "AttachmentCount", "DefaultVersionId"]),
+    );
+    expect([...schemaReadOnlyPatterns("AWS::RDS::DBInstance")]).toEqual(
+      expect.arrayContaining(["Endpoint.Address", "Endpoint.Port", "DbiResourceId", "DBInstanceStatus"]),
+    );
+    expect([...schemaReadOnlyPatterns("AWS::CE::AnomalySubscription")]).toContain("Subscribers[].Status");
+    expect(schemaReadOnlyPatterns("AWS::Made::Up").size).toBe(0);
+  });
+
+  test("ManagedPolicy: a live read carrying PolicyArn is not property drift", async () => {
+    vi.spyOn(globalThis, "fetch").mockImplementation((async (_url: string, init: { headers: Record<string, string>; body: string }) => {
+      const target = init.headers["x-amz-target"];
+      if (!target) return { status: 200, text: () => Promise.resolve(stackResources([["ReadOnly", "AWS::IAM::ManagedPolicy", "arn:aws:iam::000000000000:policy/S3VectorsReadOnlyAccess"]]).text) };
+      const r = cloudControl("arn:aws:iam::000000000000:policy/S3VectorsReadOnlyAccess", {
+        ManagedPolicyName: "S3VectorsReadOnlyAccess",
+        Path: "/",
+        PolicyDocument: { Version: "2012-10-17", Statement: [{ Effect: "Allow", Action: ["s3vectors:Get*"], Resource: "*" }] },
+        // Every readOnlyProperties entry for the type, as real AWS and the
+        // emulator return them. PolicyArn is also the primary identifier.
+        PolicyArn: "arn:aws:iam::000000000000:policy/S3VectorsReadOnlyAccess",
+        PolicyId: "ANPA000000000000EXAMPLE",
+        AttachmentCount: 1,
+        DefaultVersionId: "v1",
+        IsAttachable: true,
+        PermissionsBoundaryUsageCount: 0,
+        CreateDate: "2026-01-01T00:00:00Z",
+        UpdateDate: "2026-01-01T00:00:00Z",
+      });
+      return { status: r.status, text: () => Promise.resolve(r.text) };
+    }) as unknown as typeof fetch);
+    try {
+      const result = await deepDiffForLexicon(awsPlugin, {
+        environment: "prod",
+        buildOutput: "",
+        entities: entities({
+          ReadOnly: {
+            entityType: "AWS::IAM::ManagedPolicy",
+            props: {
+              ManagedPolicyName: "S3VectorsReadOnlyAccess",
+              PolicyDocument: { Version: "2012-10-17", Statement: [{ Effect: "Allow", Action: ["s3vectors:Get*"], Resource: "*" }] },
+            },
+          },
+        }),
+      });
+      expect(result.drifted).toEqual([]);
+      expect(result.unchanged).toEqual(["ReadOnly"]);
+    } finally {
+      vi.restoreAllMocks();
+    }
+  });
+
+  test("a second type with nested read-only paths: RDS DBInstance's endpoint and status are pruned, inputs are kept", () => {
+    const out = normalizeDeepProperties(
+      {
+        DBInstanceIdentifier: "db-1",
+        DBInstanceClass: "db.t4g.micro",
+        Endpoint: { Address: "db-1.abc.us-east-1.rds.amazonaws.com", Port: "5432", HostedZoneId: "Z1" },
+        DbiResourceId: "db-ABCDEF",
+        DBInstanceStatus: "available",
+        InstanceCreateTime: "2026-01-01T00:00:00Z",
+        CertificateDetails: { CAIdentifier: "rds-ca-rsa2048-g1", ValidTill: "2027-01-01T00:00:00Z" },
+        ProcessorFeatures: [{ Name: "coreCount", Value: "2" }],
+      },
+      { entityType: "AWS::RDS::DBInstance", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    expect(out).toEqual({
+      DBInstanceIdentifier: "db-1",
+      DBInstanceClass: "db.t4g.micro",
+      ProcessorFeatures: [{ Name: "coreCount", Value: "2" }],
+    });
+  });
+
+  test("an array element path from the schema prunes inside the array", () => {
+    const out = normalizeDeepProperties(
+      {
+        SubscriptionName: "spend",
+        Subscribers: [{ Address: "a@example.com", Type: "EMAIL", Status: "CONFIRMED" }],
+      },
+      { entityType: "AWS::CE::AnomalySubscription", side: "live", hooks: awsDeepNormalizationHooks },
+    );
+    expect(out).toEqual({
+      SubscriptionName: "spend",
+      Subscribers: [{ Address: "a@example.com", Type: "EMAIL" }],
+    });
+  });
+});
+
 describe("hasOwnershipMarker", () => {
   test("reads chant's tag out of the live tree", () => {
     expect(hasOwnershipMarker({ Tags: [{ Key: "chant:managed-by", Value: "chant" }] })).toBe(true);

package/src/deep-observe.ts

@@ -62,6 +62,9 @@ import {
 import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
 import { applyAwsEndpointArgv } from "./components/cloud-executor";
 import { toIngressRules } from "./dependencies";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
 
 /**
  * Where each type's live model comes from.
@@ -226,6 +229,58 @@ function canonicalJson(value: unknown): string {
   ) ?? "";
 }
 
+/**
+ * The read-only properties of one type, as index-erased patterns, straight from
+ * the CloudFormation schema's `readOnlyProperties` (#1641).
+ *
+ * The codegen already turns that list into each class's GetAtt attributes
+ * (`attrs` in `lexicon-aws.json`), so this reads the same registry from the
+ * other side: a path the schema says only the service can write is an
+ * attribute, and an attribute the live read reports is not property drift. No
+ * declaration can contain one, so `<undeclared> -> value` is the shape every
+ * clean apply would otherwise produce. `AWS::IAM::ManagedPolicy.PolicyArn`,
+ * which is also the type's Cloud Control primary identifier, is the case that
+ * surfaced it.
+ *
+ * The manifest spells an array element `Subscribers.*.Status`; the
+ * normalization pass spells the same thing `Subscribers[].Status`.
+ *
+ * Complements {@link AWS_READ_ONLY_NAMES} rather than replacing it: the
+ * name-based list also covers translated models (an EC2 row mapped onto the
+ * CloudFormation shape) and nested documents the schema never enumerates.
+ */
+export function schemaReadOnlyPatterns(entityType: string): ReadonlySet<string> {
+  const cached = readOnlyByType.get(entityType);
+  if (cached) return cached;
+  const entry = manifestByType().get(entityType);
+  const patterns = new Set<string>();
+  for (const attr of Object.values(entry?.attrs ?? {})) {
+    patterns.add(attr.replace(/\.\*(?=\.|$)/g, "[]"));
+  }
+  readOnlyByType.set(entityType, patterns);
+  return patterns;
+}
+
+interface ManifestEntry {
+  resourceType: string;
+  kind: string;
+  attrs?: Record<string, string>;
+}
+
+const readOnlyByType = new Map<string, ReadonlySet<string>>();
+let manifestIndex: Map<string, ManifestEntry> | undefined;
+function manifestByType(): Map<string, ManifestEntry> {
+  if (!manifestIndex) {
+    const manifest = require("./generated/lexicon-aws.json") as Record<string, ManifestEntry>;
+    manifestIndex = new Map(
+      Object.values(manifest)
+        .filter((e) => e.kind === "resource")
+        .map((e) => [e.resourceType, e]),
+    );
+  }
+  return manifestIndex;
+}
+
 /** The final segment of an index-erased pattern (`Policies[].PolicyName` → `PolicyName`). */
 function lastSegment(pattern: string): string {
   const withoutIndex = pattern.replace(/\[\]$/, "");
@@ -243,7 +298,9 @@ export const awsDeepNormalizationHooks: DeepNormalizationHooks = {
   prune(node: DeepNode): boolean {
     // Read-only / server-populated. Pruned on both sides: if source somehow
     // declares an arn-shaped output, comparing it to the live one is still
-    // meaningless.
+    // meaningless. The schema's own `readOnlyProperties` first (#1641), then
+    // the name-based list for what the schema does not enumerate.
+    if (schemaReadOnlyPatterns(node.entityType).has(node.pattern)) return true;
     if (AWS_READ_ONLY_NAMES.has(lastSegment(node.pattern))) return true;
 
     // Provider defaults, on the live side only, and only where source is silent
@@ -424,7 +481,6 @@ export async function observeResourcesDeepAws(
 
   const stackName = options.stack ?? options.environment;
   const client: AwsReadClientOptions = {
-    ...(process.env.AWS_ENDPOINT_URL ? { endpoint: process.env.AWS_ENDPOINT_URL } : {}),
     ...(options.region ? { region: options.region } : {}),
     ...(options.http ? { http: options.http } : {}),
   };

package/src/import/roundtrip-fixtures.test.ts

@@ -87,7 +87,7 @@ describe("parameters.json build roundtrip", () => {
     const result = await build(srcDir, [awsSerializer]);
     expect(result.errors).toHaveLength(0);
 
-    const template = JSON.parse(result.outputs.get("aws")!);
+    const template = JSON.parse(result.outputs.get("aws") as string);
 
     // Verify parameters round-tripped correctly (names preserved as-is)
     for (const [name, param] of Object.entries(source.Parameters ?? {})) {

package/src/index.ts

@@ -47,6 +47,8 @@ export {
   getResource,
   listResources,
   parseResourceDescription,
+  resolveEndpointOverride,
+  serviceEndpointEnvVar,
   AwsReadError,
   type AwsReadHttp,
   type AwsReadClientOptions,
@@ -126,7 +128,7 @@ export {
   Ec2InstanceRole, MinimalVpc, EksCluster,
   SolrFargateService,
   MicrovmApp, MICROVM_LIMITS,
-  AgentCoreAgent,
+  AgentCoreAgent, agentCoreDefaultEndpointArn,
   OrganizationRoot, GovernanceFoundation, RegionRestriction, OrganizationTrail,
 } from "./composites/index";
 export type {