@intentius/chant-lexicon-aws 0.124.43 → 0.124.44

package/src/import/live-export.test.ts

@@ -66,6 +66,24 @@ describe("AWS exportResources mapping (#115)", () => {
     expect(ir.resources.map((r) => r.logicalId)).toEqual(["Mine"]);
   });
 
+  test("owned filter reads map tags, UserPoolTags and the Metadata marker (#4350)", () => {
+    const tpl = {
+      AWSTemplateFormatVersion: "2010-09-09",
+      Resources: {
+        Param: { Type: "AWS::SSM::Parameter", Properties: { Type: "String", Value: "v", Tags: { "chant:managed-by": "chant" } } },
+        Pool: { Type: "AWS::Cognito::UserPool", Properties: { UserPoolTags: { "chant:managed-by": "chant" } } },
+        Reservation: {
+          Type: "AWS::EC2::CapacityReservation",
+          Metadata: { "chant:ownership": { "chant:managed-by": "chant" } },
+          Properties: { InstanceType: "t3.micro" },
+        },
+        Theirs: { Type: "AWS::SSM::Parameter", Properties: { Type: "String", Value: "v", Tags: { team: "other" } } },
+      },
+    };
+    const ir = parseStackTemplate(tpl, undefined, true);
+    expect(ir.resources.map((r) => r.logicalId)).toEqual(["Param", "Pool", "Reservation"]);
+  });
+
   test("export IR feeds CFGenerator (templateGenerator) unchanged", () => {
     const ir = parseStackTemplate(liveTemplate);
     const files = new CFGenerator().generate(ir);

package/src/import/live-export.ts

@@ -1,6 +1,7 @@
 import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
-import { hasOwnershipMarker, tagArrayToMap } from "@intentius/chant/ownership";
-import { AWS_TAG_OWNERSHIP_KEYS } from "../ownership";
+import { hasOwnershipMarker } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS, OWNERSHIP_METADATA_KEY } from "../ownership";
+import { readResourceTags, readTagValue } from "../taggable";
 import { CFParser } from "./parser";
 
 /**
@@ -30,8 +31,11 @@ export function parseStackTemplate(
       if (selector?.type !== undefined && r.type !== selector.type) return false;
       if (selector?.name !== undefined && r.logicalId !== selector.name) return false;
       if (owned) {
-        const tags = (r.properties as { Tags?: Array<{ Key?: string; Value?: unknown }> }).Tags;
-        if (!hasOwnershipMarker(tagArrayToMap(tags), AWS_TAG_OWNERSHIP_KEYS)) return false;
+        // The marker sits in the type's own tag property, in either shape, or
+        // in the resource's Metadata for a type whose tags can't be stamped (#4350).
+        const tags = readResourceTags(r.type, r.properties as Record<string, unknown>);
+        const marker = readTagValue(r.metadata?.[OWNERSHIP_METADATA_KEY]);
+        if (!hasOwnershipMarker(tags, AWS_TAG_OWNERSHIP_KEYS) && !hasOwnershipMarker(marker, AWS_TAG_OWNERSHIP_KEYS)) return false;
       }
       return true;
     }),

package/src/lint/audit-catalog.ts

@@ -91,6 +91,7 @@ export const awsAuditCatalog: Record<string, RuleMeta> = {
   WAW068: auditRule("WAW068", "report-only", "guidance", "VPN Gateway or Transit Gateway has only one attached VPN Connection", "Attach a second VPNConnection (ideally to a separate Customer Gateway) for redundancy.", { category: "best-practice" }),
   WAW069: auditRule("WAW069", "merge-worthy", "guidance", "Template references a condition it never declares", "Declare the condition in the Conditions section (new Condition(...)), or fix the referenced name.", { category: "correctness" }),
   WAW070: auditRule("WAW070", "merge-worthy", "guidance", "Ref or Fn::GetAtt names something the template doesn't declare", "Reference a resource or parameter in this template. A value from another lexicon's resource arrives as a parameter.", { category: "correctness" }),
+  WAW071: auditRule("WAW071", "merge-worthy", "guidance", "Tags are in the wrong property or the wrong shape for the resource type", "Write the tags in the property the type uses and in the shape it takes, which is a list of Key and Value pairs for most types and a map for some, such as UserPoolTags on AWS::Cognito::UserPool.", { category: "correctness" }),
 };
 
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).

package/src/lint/audit-lineage.ts

@@ -160,4 +160,8 @@ export const awsAuditLineage: Record<string, Lineage[]> = {
     { tool: "cfn-lint", rule: "E1012", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E1012", relation: "equivalent" },
     { tool: "cfn-lint", rule: "E1010", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E1010", relation: "overlaps" },
   ],
+  WAW071: [
+    { tool: "cfn-lint", rule: "E3002", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E3002", relation: "overlaps" },
+    { tool: "cfn-lint", rule: "E3012", url: "https://github.com/aws-cloudformation/cfn-lint/blob/main/docs/rules.md#E3012", relation: "overlaps" },
+  ],
 };

package/src/lint/post-synth/index.ts

@@ -62,6 +62,7 @@ import { waw067 } from "./waw067";
 import { waw068 } from "./waw068";
 import { waw069 } from "./waw069";
 import { waw070 } from "./waw070";
+import { waw071 } from "./waw071";
 
 export const postSynthChecks: PostSynthCheck[] = [
   cor020,
@@ -126,4 +127,5 @@ export const postSynthChecks: PostSynthCheck[] = [
   waw068,
   waw069,
   waw070,
+  waw071,
 ];

package/src/lint/post-synth/waw017.ts

@@ -7,7 +7,7 @@
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { parseCFTemplate } from "./cf-refs";
-import { loadTaggableResources } from "../../taggable";
+import { loadTaggableResources, tagPlacementFor } from "../../taggable";
 
 /**
  * Core detection logic — exported for direct testing with synthetic data.
@@ -28,7 +28,8 @@ export function checkMissingTags(
       if (!taggable.has(resource.Type)) continue;
 
       const props = resource.Properties ?? {};
-      if (!("Tags" in props)) {
+      const tagProperty = tagPlacementFor(resource.Type)?.property ?? "Tags";
+      if (!(tagProperty in props)) {
         diagnostics.push({
           checkId: "WAW017",
           severity: "warning",

package/src/lint/post-synth/waw071.test.ts

@@ -0,0 +1,50 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw071, checkTagShapes } from "./waw071";
+import type { TagPlacement } from "../../taggable";
+
+const placements = new Map<string, TagPlacement | null>([
+  ["AWS::S3::Bucket", { property: "Tags", shape: "list" }],
+  ["AWS::SSM::Parameter", { property: "Tags", shape: "map" }],
+  ["AWS::Cognito::UserPool", { property: "UserPoolTags", shape: "map" }],
+  ["AWS::EC2::CapacityReservation", null],
+]);
+
+function check(resources: Record<string, unknown>) {
+  return checkTagShapes(createPostSynthContext({ aws: { Resources: resources } }), placements);
+}
+
+describe("WAW071: tags in the wrong property or shape", () => {
+  test("check metadata", () => {
+    expect(waw071.id).toBe("WAW071");
+  });
+
+  test("flags Tags on a user pool", () => {
+    const d = check({ Pool: { Type: "AWS::Cognito::UserPool", Properties: { Tags: [{ Key: "a", Value: "b" }] } } });
+    expect(d).toHaveLength(1);
+    expect(d[0].message).toContain("UserPoolTags");
+    expect(d[0].severity).toBe("error");
+  });
+
+  test("flags a list on a map type", () => {
+    const d = check({ P: { Type: "AWS::SSM::Parameter", Properties: { Tags: [{ Key: "a", Value: "b" }] } } });
+    expect(d).toHaveLength(1);
+    expect(d[0].message).toContain("map");
+  });
+
+  test("flags a map on a list type", () => {
+    const d = check({ B: { Type: "AWS::S3::Bucket", Properties: { Tags: { a: "b" } } } });
+    expect(d).toHaveLength(1);
+  });
+
+  test("passes the right shapes, intrinsics and unplaceable types", () => {
+    const d = check({
+      B: { Type: "AWS::S3::Bucket", Properties: { Tags: [{ Key: "a", Value: { Ref: "X" } }, { "Fn::If": ["C", { Key: "k", Value: "v" }, { Ref: "AWS::NoValue" }] }] } },
+      P: { Type: "AWS::SSM::Parameter", Properties: { Tags: { a: "b" } } },
+      Pool: { Type: "AWS::Cognito::UserPool", Properties: { UserPoolTags: { a: "b" } } },
+      Q: { Type: "AWS::SSM::Parameter", Properties: { Tags: { "Fn::If": ["C", { a: "b" }, {}] } } },
+      CR: { Type: "AWS::EC2::CapacityReservation", Properties: { Tags: [] } },
+    });
+    expect(d).toEqual([]);
+  });
+});

package/src/lint/post-synth/waw071.ts

@@ -0,0 +1,85 @@
+/**
+ * WAW071: Tags are in the wrong property or the wrong shape for the type
+ *
+ * Each taggable type names its tag property and shape in its schema
+ * (`tagging.tagProperty`): a `[{Key, Value}]` list for most types, a map for
+ * types such as `AWS::SSM::Parameter`, and a property other than `Tags` for
+ * types such as `AWS::Cognito::UserPool` (`UserPoolTags`). CloudFormation
+ * rejects a template that puts tags anywhere else. chant stamped the ownership
+ * marker as a `Tags` list on every type until #4350; this check catches the
+ * next such template.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate } from "./cf-refs";
+import { isTagIntrinsic, loadTagPlacements, type TagPlacement } from "../../taggable";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Why `value` doesn't fit `placement`, or undefined when it does. */
+function shapeProblem(value: unknown, placement: TagPlacement): string | undefined {
+  if (isTagIntrinsic(value)) return undefined;
+  if (placement.shape === "map") {
+    return isPlainObject(value) ? undefined : "a list, but the type takes a key-to-value map";
+  }
+  if (!Array.isArray(value)) return "a map, but the type takes a [{Key, Value}] list";
+  const bad = value.some((t) => !isTagIntrinsic(t) && !(isPlainObject(t) && "Key" in t && "Value" in t));
+  return bad ? "a list with an entry that has no Key and Value" : undefined;
+}
+
+/**
+ * Core detection logic — exported for direct testing with synthetic data.
+ */
+export function checkTagShapes(
+  ctx: PostSynthContext,
+  placements: Map<string, TagPlacement | null>,
+): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [lexicon, output] of ctx.outputs) {
+    if (lexicon !== "aws") continue;
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      const placement = placements.get(resource.Type);
+      if (!placement) continue;
+      const props = resource.Properties ?? {};
+
+      if (placement.property !== "Tags" && "Tags" in props) {
+        diagnostics.push({
+          checkId: "WAW071",
+          severity: "error",
+          message: `Resource "${logicalId}" (${resource.Type}) has Tags, but the type takes its tags in ${placement.property}`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+
+      if (!(placement.property in props)) continue;
+      const problem = shapeProblem(props[placement.property], placement);
+      if (problem) {
+        diagnostics.push({
+          checkId: "WAW071",
+          severity: "error",
+          message: `Resource "${logicalId}" (${resource.Type}) has ${placement.property} as ${problem}`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw071: PostSynthCheck = {
+  id: "WAW071",
+  description: "Tags are in the wrong property or the wrong shape for the resource type",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkTagShapes(ctx, loadTagPlacements());
+  },
+};

package/src/serializer-tag-shapes.test.ts

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "vitest";
+import { awsSerializer, mergeTags } from "./serializer";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { loadTagPlacements } from "./taggable";
+
+class MockResource implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "aws";
+  constructor(readonly entityType: string, readonly props: Record<string, unknown> = {}) {}
+}
+
+const OWNERSHIP = { stack: "loom", env: "dev" };
+const MARKER = { "chant:managed-by": "chant", "chant:stack": "loom", "chant:env": "dev" };
+
+function build(type: string, props: Record<string, unknown> = {}) {
+  const entities = new Map<string, Declarable>([["R", new MockResource(type, props)]]);
+  const template = JSON.parse(awsSerializer.serialize(entities, [], { ownership: OWNERSHIP }) as string);
+  return template.Resources.R as { Properties?: Record<string, unknown>; Metadata?: Record<string, unknown> };
+}
+
+describe("tag placements from the generated lexicon (#4350)", () => {
+  test("reads property and shape per type", () => {
+    const p = loadTagPlacements();
+    expect(p.get("AWS::S3::Bucket")).toEqual({ property: "Tags", shape: "list" });
+    expect(p.get("AWS::SSM::Parameter")).toEqual({ property: "Tags", shape: "map" });
+    expect(p.get("AWS::BedrockAgentCore::Runtime")).toEqual({ property: "Tags", shape: "map" });
+    expect(p.get("AWS::BedrockAgentCore::Memory")).toEqual({ property: "Tags", shape: "map" });
+    expect(p.get("AWS::Cognito::UserPool")).toEqual({ property: "UserPoolTags", shape: "map" });
+    expect(p.get("AWS::EC2::CapacityReservation")).toBeNull();
+  });
+});
+
+describe("ownership stamping by tag shape (#4350)", () => {
+  test("list type gets a [{Key, Value}] list in Tags", () => {
+    const r = build("AWS::S3::Bucket", { BucketName: "b" });
+    expect(r.Properties!.Tags).toEqual(Object.entries(MARKER).map(([Key, Value]) => ({ Key, Value })));
+  });
+
+  test("map type gets a map in Tags", () => {
+    const r = build("AWS::SSM::Parameter", { Type: "String", Value: "v" });
+    expect(r.Properties!.Tags).toEqual(MARKER);
+  });
+
+  test("Cognito user pool gets UserPoolTags, and no Tags", () => {
+    const r = build("AWS::Cognito::UserPool", { UserPoolName: "p", UserPoolTags: { component: "loom-cognito" } });
+    expect(r.Properties!.Tags).toBeUndefined();
+    expect(r.Properties!.UserPoolTags).toEqual({ ...MARKER, component: "loom-cognito" });
+  });
+
+  test("explicit map tags merge on a map type, explicit key wins", () => {
+    const r = build("AWS::SSM::Parameter", { Type: "String", Value: "v", Tags: { team: "a", "chant:env": "override" } });
+    expect(r.Properties!.Tags).toEqual({ ...MARKER, team: "a", "chant:env": "override" });
+  });
+
+  test("explicit list tags on a map type are converted", () => {
+    const r = build("AWS::SSM::Parameter", { Type: "String", Value: "v", Tags: [{ Key: "team", Value: "a" }] });
+    expect(r.Properties!.Tags).toEqual({ ...MARKER, team: "a" });
+  });
+
+  test("explicit map tags on a list type are converted", () => {
+    const r = build("AWS::S3::Bucket", { Tags: { team: "a" } });
+    expect(r.Properties!.Tags).toContainEqual({ Key: "team", Value: "a" });
+    expect(r.Properties!.Tags).toContainEqual({ Key: "chant:managed-by", Value: "chant" });
+  });
+
+  test("a type it can't place gets the marker in its own Metadata, not a Tags property", () => {
+    const r = build("AWS::EC2::CapacityReservation", { InstanceType: "t3.micro" });
+    expect(r.Properties!.Tags).toBeUndefined();
+    expect(r.Metadata!["chant:ownership"]).toEqual(MARKER);
+  });
+});
+
+describe("mergeTags", () => {
+  const stamped = [{ Key: "chant:managed-by", Value: "chant" }];
+  test("an intrinsic explicit value can't be merged", () => {
+    expect(mergeTags({ "Fn::If": ["C", [], []] }, stamped, { property: "Tags", shape: "list" })).toBeUndefined();
+    expect(mergeTags({ Ref: "T" }, stamped, { property: "Tags", shape: "map" })).toBeUndefined();
+  });
+  test("no explicit value stamps alone", () => {
+    expect(mergeTags(undefined, stamped, { property: "Tags", shape: "map" })).toEqual({ "chant:managed-by": "chant" });
+    expect(mergeTags(undefined, stamped, { property: "Tags", shape: "list" })).toEqual(stamped);
+  });
+});

package/src/serializer.ts

@@ -26,7 +26,7 @@ import { isMapping } from "./mapping";
 import { isDefaultTags, type TagEntry } from "./default-tags";
 import { isTemplateTransform } from "./template-transform";
 import { isTemplateSection } from "./template-sections";
-import { loadTaggableResources } from "./taggable";
+import { isTagIntrinsic, loadTagPlacements, readTagValue, type TagPlacement } from "./taggable";
 
 /**
  * Check if a declarable is a CoreParameter
@@ -292,6 +292,33 @@ function renderReceiptRows(
   return rows;
 }
 
+/**
+ * Merge stamped default tags under a resource's explicit tags, in the type's
+ * tag shape (#4350). Explicit tags win on a key clash. Explicit tags of the
+ * other shape are converted, so a map written on a list type still merges.
+ * Returns undefined when the explicit value is an intrinsic, which can't be
+ * merged into.
+ */
+export function mergeTags(
+  explicit: unknown,
+  stamped: Array<{ Key: string; Value: unknown }>,
+  placement: TagPlacement,
+): unknown {
+  if (explicit !== undefined && (isTagIntrinsic(explicit) || (typeof explicit !== "object" || explicit === null))) {
+    return undefined;
+  }
+  if (placement.shape === "map") {
+    const merged: Record<string, unknown> = {};
+    for (const t of stamped) merged[t.Key] = t.Value;
+    return { ...merged, ...readTagValue(explicit) };
+  }
+  const explicitList = Array.isArray(explicit)
+    ? (explicit as Array<{ Key?: unknown }>)
+    : Object.entries(readTagValue(explicit)).map(([Key, Value]) => ({ Key, Value }));
+  const explicitKeys = new Set(explicitList.map(t => t?.Key));
+  return [...stamped.filter(t => !explicitKeys.has(t.Key)), ...explicitList];
+}
+
 /**
  * Serialize a set of entities into a CFTemplate object (without JSON.stringify).
  */
@@ -510,20 +537,30 @@ function serializeToTemplate(
     }
   }
 
-  // Inject default tags into taggable resources
+  // Inject default tags into taggable resources, each through its own tag
+  // property and shape (#4350): `UserPoolTags` on a Cognito user pool, a map on
+  // an SSM parameter, a `[{Key, Value}]` list elsewhere.
   if (defaultTagEntries.length > 0) {
-    const taggable = loadTaggableResources();
+    const placements = loadTagPlacements();
     for (const [, resource] of Object.entries(template.Resources)) {
-      if (!taggable.has(resource.Type)) continue;
+      const placement = placements.get(resource.Type);
+      if (placement === undefined) continue;
       const resolved = defaultTagEntries.map(t => ({
         Key: t.Key,
         Value: toCFValue(t.Value, entityNames),
       }));
-      const explicit = (resource.Properties?.Tags ?? []) as Array<{ Key: string }>;
-      const explicitKeys = new Set(explicit.map(t => t.Key));
-      const merged = [...resolved.filter(t => !explicitKeys.has(t.Key)), ...explicit];
-      if (!resource.Properties) resource.Properties = {};
-      resource.Properties.Tags = merged;
+      const stamped = placement ? mergeTags(resource.Properties?.[placement.property], resolved, placement) : undefined;
+      if (stamped !== undefined) {
+        if (!resource.Properties) resource.Properties = {};
+        resource.Properties[placement!.property] = stamped;
+      } else if (ownership) {
+        // Nowhere valid to write the tags, so the marker goes on the resource's
+        // own Metadata instead of an invalid property.
+        resource.Metadata = {
+          ...(resource.Metadata ?? {}),
+          [OWNERSHIP_METADATA_KEY]: ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership),
+        };
+      }
     }
   }
 

package/src/spec/parse.test.ts

@@ -4,6 +4,7 @@ import {
   cfnShortName,
   cfnServiceName,
   stripPointerPath,
+  tagPlacement,
 } from "./parse";
 import type { CFNSchema } from "./fetch";
 
@@ -496,3 +497,41 @@ describe("cfnServiceName", () => {
     expect(cfnServiceName("AWS::IAM::Role")).toBe("IAM");
   });
 });
+
+describe("tagPlacement (#4350)", () => {
+  const base = { typeName: "AWS::Test::T", additionalProperties: false };
+  test("a Key/Value list in Tags", () => {
+    expect(tagPlacement({
+      ...base,
+      properties: { Tags: { type: "array", items: { $ref: "#/definitions/Tag" } } },
+      definitions: { Tag: { type: "object", properties: { Key: { type: "string" }, Value: { type: "string" } } } },
+      tagging: { taggable: true, tagProperty: "/properties/Tags" },
+    } as CFNSchema)).toEqual({ tagProperty: "Tags", tagShape: "list" });
+  });
+  test("a map under another property name", () => {
+    expect(tagPlacement({
+      ...base,
+      properties: { UserPoolTags: { type: "object", patternProperties: { ".*": { type: "string" } } } as never },
+      tagging: { taggable: true, tagProperty: "/properties/UserPoolTags" },
+    } as CFNSchema)).toEqual({ tagProperty: "UserPoolTags", tagShape: "map" });
+  });
+  test("Tags when tagProperty is absent", () => {
+    expect(tagPlacement({
+      ...base,
+      properties: { Tags: { type: "object" } },
+      tagging: { taggable: true },
+    } as CFNSchema)).toEqual({ tagProperty: "Tags", tagShape: "map" });
+  });
+  test("nothing for a path inside an array or a wrapper object", () => {
+    expect(tagPlacement({
+      ...base,
+      properties: { TagSpecifications: { type: "array" } },
+      tagging: { taggable: true, tagProperty: "/properties/TagSpecifications/*/Tags" },
+    } as CFNSchema)).toEqual({});
+    expect(tagPlacement({
+      ...base,
+      properties: { Tags: { type: "object", properties: { Items: { type: "array" } } } },
+      tagging: { taggable: true, tagProperty: "/properties/Tags" },
+    } as CFNSchema)).toEqual({});
+  });
+});

package/src/spec/parse.ts

@@ -79,7 +79,24 @@ export interface ParsedResource {
   inferredDeprecations: string[];
   conditionalCreateOnly: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
-  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
+  tagging?: ResourceTagging;
+}
+
+/** How a type's tags are written: a `[{Key, Value}]` list or a key-to-value map. */
+export type TagShape = "list" | "map";
+
+export interface ResourceTagging {
+  taggable: boolean;
+  tagOnCreate: boolean;
+  tagUpdatable: boolean;
+  /**
+   * The top-level property the type's tags live in (`Tags`, `UserPoolTags`, ...)
+   * and its shape, read from the schema's `tagging.tagProperty` (#4350). Both are
+   * absent when the tags sit somewhere the serializer can't stamp, such as
+   * a path inside an array (`TagSpecifications[].Tags`) or an `{Items: [...]}` wrapper.
+   */
+  tagProperty?: string;
+  tagShape?: TagShape;
 }
 
 export interface SchemaParseResult {
@@ -202,6 +219,7 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
       taggable: true,
       tagOnCreate: schema.tagging.tagOnCreate ?? false,
       tagUpdatable: schema.tagging.tagUpdatable ?? false,
+      ...tagPlacement(schema),
     };
   }
 
@@ -242,6 +260,70 @@ export function parseCFNSchema(data: string | Buffer): SchemaParseResult {
 
 // --- Type resolution (delegated to core) ---
 
+/**
+ * Where a taggable type's tags go and in which shape (#4350). The property is
+ * `tagging.tagProperty` when it names one top-level property, else `Tags` when
+ * the type has one. The shape is a list when the items carry `Key` and `Value`
+ * (directly or as one `oneOf` branch) and a map when the property is an object
+ * with no fixed properties. Anything else returns `{}`, so the type is skipped.
+ */
+export function tagPlacement(schema: CFNSchema): { tagProperty?: string; tagShape?: TagShape } {
+  const pointer = schema.tagging?.tagProperty;
+  let name: string | undefined;
+  if (pointer !== undefined) {
+    const m = /^\/properties\/([^/]+)$/.exec(pointer);
+    if (!m) return {};
+    name = m[1];
+  } else if (schema.properties?.Tags) {
+    name = "Tags";
+  }
+  if (name === undefined) return {};
+  const prop = resolveLocalRef(schema.properties?.[name], schema);
+  if (!prop) return {};
+  const shape = tagShapeOf(prop, schema);
+  return shape ? { tagProperty: name, tagShape: shape } : {};
+}
+
+type LooseSchema = Record<string, unknown> & {
+  $ref?: string;
+  type?: string | string[];
+  items?: unknown;
+  properties?: Record<string, unknown>;
+  oneOf?: unknown[];
+  anyOf?: unknown[];
+  patternProperties?: unknown;
+  additionalProperties?: unknown;
+};
+
+function resolveLocalRef(value: unknown, schema: CFNSchema): LooseSchema | undefined {
+  let node = value as LooseSchema | undefined;
+  for (let i = 0; i < 8 && node && typeof node.$ref === "string"; i++) {
+    const def = refDefinitionName(node.$ref);
+    node = def ? (schema.definitions?.[def] as LooseSchema | undefined) : undefined;
+  }
+  return node && typeof node === "object" ? node : undefined;
+}
+
+function hasType(node: LooseSchema, t: string): boolean {
+  return node.type === t || (Array.isArray(node.type) && node.type.includes(t));
+}
+
+function isKeyValueItem(node: LooseSchema | undefined, schema: CFNSchema): boolean {
+  if (!node) return false;
+  if (node.properties && "Key" in node.properties && "Value" in node.properties) return true;
+  const branches = [...(node.oneOf ?? []), ...(node.anyOf ?? [])];
+  return branches.some((b) => isKeyValueItem(resolveLocalRef(b, schema), schema));
+}
+
+function tagShapeOf(prop: LooseSchema, schema: CFNSchema): TagShape | undefined {
+  if (hasType(prop, "array")) {
+    return isKeyValueItem(resolveLocalRef(prop.items, schema), schema) ? "list" : undefined;
+  }
+  const objectish = hasType(prop, "object") || prop.patternProperties !== undefined || prop.additionalProperties !== undefined;
+  if (objectish && (!prop.properties || Object.keys(prop.properties).length === 0)) return "map";
+  return undefined;
+}
+
 function resolvePropertyType(prop: SchemaProperty | undefined, schema: CFNSchema): string {
   const shortName = cfnShortName(schema.typeName);
   return coreResolvePropertyType(