@intentius/chant-lexicon-aws 0.124.23 → 0.124.25

package/src/codegen/property-overlay.ts

@@ -0,0 +1,125 @@
+/**
+ * Backfilled properties (chant #3953).
+ *
+ * The Registry spec is pinned by content (src/spec/pin.ts), so a property AWS
+ * adds after the pin was accepted does not reach the generated types until the
+ * pin moves. Moving it is a reviewed, whole-spec decision: the 2026-08-05 pin
+ * against the October upstream is 185 resource types apart. When one property
+ * is needed before that, it goes here instead of being cast past the types.
+ *
+ * Each entry names a top-level property and the schema fragment to add for it,
+ * copied from the live Registry schema. It is merged into the raw schema before
+ * parsing, so the property reaches the `.d.ts` and the lexicon registry by the
+ * same path a spec property does. The overlay has no way to mark a property
+ * create-only, so it only suits properties that are updatable in place.
+ *
+ * Precedence follows the enum overlay (#1497): where the spec already declares
+ * the property, the spec wins and the entry is reported as redundant, so a pin
+ * bump surfaces the entries it retires.
+ */
+
+import overlayDocument from "./property-overlay.json" with { type: "json" };
+
+/** One backfilled property. */
+export interface PropertyOverlayEntry {
+  /** CloudFormation type name, e.g. `AWS::BedrockAgentCore::Runtime`. */
+  type: string;
+  /** Top-level property name, added under `/properties`. */
+  property: string;
+  /** The chant issue that asked for it. */
+  issue: number;
+  /** Where the schema fragment was copied from. */
+  source: string;
+  /** ISO date the fragment was last read from `source`. */
+  reviewed: string;
+  /** JSON Schema for the property, as the Registry schema declares it. */
+  schema: Record<string, unknown>;
+}
+
+/** What happened to one entry during a generation run. */
+export interface PropertyOverlayApplication {
+  entry: PropertyOverlayEntry;
+  /** `applied` added the property; `redundant` found the spec already declares it. */
+  outcome: "applied" | "redundant";
+}
+
+/** The backfilled entries, in file order. */
+export function propertyOverlayEntries(): PropertyOverlayEntry[] {
+  return overlayDocument.entries as PropertyOverlayEntry[];
+}
+
+/** Entries grouped by CloudFormation type name. */
+export function propertyOverlayByType(
+  entries: PropertyOverlayEntry[] = propertyOverlayEntries(),
+): Map<string, PropertyOverlayEntry[]> {
+  const byType = new Map<string, PropertyOverlayEntry[]>();
+  for (const entry of entries) {
+    const list = byType.get(entry.type);
+    if (list) list.push(entry);
+    else byType.set(entry.type, [entry]);
+  }
+  return byType;
+}
+
+/** Add the entries for one CloudFormation type to its raw schema bytes. */
+export function applyPropertyOverlay(
+  data: Buffer | string,
+  entries: PropertyOverlayEntry[],
+): { data: Buffer | string; applications: PropertyOverlayApplication[] } {
+  if (entries.length === 0) return { data, applications: [] };
+
+  const text = typeof data === "string" ? data : data.toString("utf-8");
+  const doc = JSON.parse(text) as Record<string, unknown>;
+  const properties = (doc.properties ??= {}) as Record<string, unknown>;
+  const applications: PropertyOverlayApplication[] = [];
+  let changed = false;
+
+  for (const entry of entries) {
+    if (entry.property in properties) {
+      applications.push({ entry, outcome: "redundant" });
+      continue;
+    }
+    properties[entry.property] = structuredClone(entry.schema);
+    changed = true;
+    applications.push({ entry, outcome: "applied" });
+  }
+
+  if (!changed) return { data, applications };
+  const rewritten = JSON.stringify(doc);
+  return {
+    data: typeof data === "string" ? rewritten : Buffer.from(rewritten),
+    applications,
+  };
+}
+
+/**
+ * Fail on an entry whose type the run never saw. Only a run over the real
+ * schema zip is strict; a fixture run legitimately lacks most types.
+ */
+export function assertPropertyOverlayCoverage(
+  entries: PropertyOverlayEntry[],
+  seenTypes: Set<string>,
+  strict: boolean,
+): void {
+  if (!strict) return;
+  const missing = [...new Set(entries.filter((e) => !seenTypes.has(e.type)).map((e) => e.type))];
+  if (missing.length === 0) return;
+  throw new Error(
+    `property overlay names type(s) the spec does not contain: ${missing.sort().join(", ")}. ` +
+      `Drop them from src/codegen/property-overlay.json or fix the type name.`,
+  );
+}
+
+/** One warning line per entry the spec has caught up with. */
+export function redundantPropertyOverlayWarnings(
+  applications: PropertyOverlayApplication[],
+): Array<{ file: string; error: string }> {
+  return applications
+    .filter((a) => a.outcome === "redundant")
+    .map((a) => ({
+      file: `${a.entry.type}/properties/${a.entry.property}`,
+      error:
+        `property overlay entry is redundant: the spec already declares this property, ` +
+        `and the spec wins. Retire the entry from src/codegen/property-overlay.json.`,
+    }));
+}

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

@@ -6,7 +6,8 @@ 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, agentCoreDefaultEndpointArn } from "./agentcore-agent";
+import { AgentCoreAgent, agentCoreDefaultEndpointArn, type AgentCoreAgentProps } from "./agentcore-agent";
+import { Runtime } from "../generated";
 import { Split, Ref } from "../intrinsics";
 import { awsSerializer } from "../serializer";
 
@@ -262,6 +263,30 @@ describe("AgentCoreAgent", () => {
     expect(endpointProps.Description).toBe("prod alias");
   });
 
+  test("defaults.runtime takes PlatformVersion, typed, and it reaches the template (#3953)", () => {
+    // Typed on purpose: the backfilled property must be accepted without a cast.
+    const runtimeDefaults: AgentCoreAgentProps["defaults"] = { runtime: { PlatformVersion: "2" } };
+    const expanded = expandComposite("agent", AgentCoreAgent({ ...baseProps, defaults: runtimeDefaults }));
+    resolveAttrRefs(expanded);
+    const template = JSON.parse(awsSerializer.serialize(expanded) as string);
+    expect(template.Resources.agentRuntime.Properties.PlatformVersion).toBe("2");
+  });
+
+  test("a Runtime built directly with PlatformVersion emits it (#3953)", () => {
+    const runtime = new Runtime({
+      AgentRuntimeName: "support_agent",
+      AgentRuntimeArtifact: { ContainerConfiguration: { ContainerUri: baseProps.containerUri } },
+      NetworkConfiguration: { NetworkMode: "PUBLIC" },
+      RoleArn: "arn:aws:iam::123456789012:role/agent",
+      PlatformVersion: "2",
+    });
+    const template = JSON.parse(awsSerializer.serialize(new Map([["agentRuntime", runtime]])) as string);
+    expect(template.Resources.agentRuntime).toMatchObject({
+      Type: "AWS::BedrockAgentCore::Runtime",
+      Properties: { AgentRuntimeName: "support_agent", PlatformVersion: "2" },
+    });
+  });
+
   test("serializes to a valid CloudFormation template with the expected resource types", () => {
     const expanded = expandComposite("agent", AgentCoreAgent(withEndpoint));
     resolveAttrRefs(expanded);

package/src/generated/index.d.ts

@@ -30885,6 +30885,8 @@ export declare class Runtime {
     LastUpdatedAt?: string;
     /** Lifecycle configuration for managing runtime sessions */
     LifecycleConfiguration?: Runtime_LifecycleConfiguration;
+    /** The version of the runtime platform */
+    PlatformVersion?: string;
     /** Protocol configuration for the agent runtime */
     ProtocolConfiguration?: Runtime_ProtocolConfiguration;
     /** Configuration for HTTP request headers */

package/src/generated/lexicon-aws.json

@@ -87930,6 +87930,13 @@
       "WorkloadIdentityDetails": "WorkloadIdentityDetails",
       "FailureReason": "FailureReason"
     },
+    "propertyConstraints": {
+      "PlatformVersion": {
+        "pattern": "^[^\\s]+$",
+        "minLength": 1,
+        "maxLength": 128
+      }
+    },
     "createOnly": [
       "AgentRuntimeName"
     ],

package/src/op/activities/floci.test.ts

@@ -32,6 +32,32 @@ describe("flociRunCommand (#704)", () => {
   });
 });
 
+describe("flociRunCommand image, network, settings and loopback (#3952)", () => {
+  test("the default image stays the pinned one when only other options are given", () => {
+    expect(flociRunCommand({ network: "loom" }).endsWith("floci/floci:1.5.34")).toBe(true);
+  });
+
+  test("all four options together, in the argv docker gets", () => {
+    expect(
+      flociRunCommand({
+        image: "floci/floci:1.6.0",
+        network: "loom-local",
+        settings: { FLOCI_STORAGE_MODE: "memory" },
+        loopback: true,
+        dockerSocket: true,
+      }),
+    ).toBe(
+      "docker run -d --rm --name chant-floci -p 127.0.0.1:4566:4566 --network loom-local " +
+        "-e FLOCI_STORAGE_MODE=memory -v /var/run/docker.sock:/var/run/docker.sock floci/floci:1.6.0",
+    );
+  });
+
+  test("a setting that is not FLOCI_* is refused, not passed to the container", () => {
+    expect(() => flociRunCommand({ settings: { AWS_SECRET_ACCESS_KEY: "x" } })).toThrow(/not a FLOCI_\* variable/);
+    expect(FLOCI_SPEC.settingsPrefix).toBe("FLOCI_");
+  });
+});
+
 describe("flociRmCommand / flociExistsCommand (#704)", () => {
   test("rm force-removes the container", () => {
     expect(flociRmCommand("chant-floci")).toBe("docker rm -f chant-floci");

package/src/op/activities/floci.ts

@@ -16,8 +16,17 @@ export interface FlociUpArgs {
   name?: string;
   /** Host port mapped to the emulator's `:4566`. Default: `4566`. */
   port?: number;
-  /** Floci image. Default: `floci/floci:latest`. */
+  /** Floci image. Default: the pinned `floci/floci:1.5.34`. */
   image?: string;
+  /** Docker network the container joins, e.g. a compose network other containers reach Floci on. */
+  network?: string;
+  /**
+   * Extra Floci settings, passed to the container as `-e KEY=VALUE`. Every key
+   * must start with `FLOCI_`; any other key is refused rather than passed on.
+   */
+  settings?: Record<string, string>;
+  /** Publish the port on 127.0.0.1 only, instead of every host interface. Default: `false`. */
+  loopback?: boolean;
   /** Mount the docker socket — Floci needs it for the ECR backing registry. Default: `false`. */
   dockerSocket?: boolean;
   /** `AWS_REGION` exported for subsequent steps. Default: `us-east-1`. */
@@ -60,6 +69,7 @@ const flociSpecFor = (readyService: string): EmulatorSpec => ({
   healthPath: "/_localstack/health",
   ready: (body) => isFlociReady(body, readyService),
   upstream: { repo: "floci-io/floci" },
+  settingsPrefix: "FLOCI_",
 });
 
 /** The Floci emulator spec — the aws plugin's `emulator` capability (#920). */
@@ -91,6 +101,9 @@ export function flociRunCommand(args: FlociUpArgs = {}): string {
     name: args.name,
     port: args.port,
     image: args.image,
+    network: args.network,
+    settings: args.settings,
+    loopback: args.loopback,
     extraArgs: args.dockerSocket ? [...DOCKER_SOCK] : [],
   });
 }
@@ -113,6 +126,9 @@ export async function flociUp(args: FlociUpArgs = {}, signal?: AbortSignal): Pro
       name: args.name,
       port: args.port,
       image: args.image,
+      network: args.network,
+      settings: args.settings,
+      loopback: args.loopback,
       timeoutMs: args.timeoutMs,
       intervalMs: args.intervalMs,
       extraArgs: args.dockerSocket ? [...DOCKER_SOCK] : [],