@intentius/chant-lexicon-aws 0.124.43 → 0.124.45

package/dist/okf/index.md

@@ -1937,3 +1937,4 @@ okf_version: '0.2'
 * [WAW068](/rules/WAW068.md) - VPN Gateway or Transit Gateway has only one attached VPN Connection — no redundant path for hybrid connectivity
 * [WAW069](/rules/WAW069.md) - Template references a condition it never declares — resource/output Condition keys, Fn::If, and Condition references must name an entry in the Conditions sec...
 * [WAW070](/rules/WAW070.md) - Ref or Fn::GetAtt names something the template doesn't declare
+* [WAW071](/rules/WAW071.md) - Tags are in the wrong property or the wrong shape for the resource type

package/dist/okf/rules/WAW071.md

@@ -0,0 +1,19 @@
+---
+type: post-synth-check
+title: WAW071
+description: Tags are in the wrong property or the wrong shape for the resource type
+id: WAW071
+severity: error
+category: post-synth
+lexicon: aws
+docs: https://intentius.io/chant/lexicons/aws/rules/
+---
+Tags are in the wrong property or the wrong shape for the resource type
+
+## Applies to
+
+- [Key](/types/Key.md)
+- [Map](/types/Map.md)
+- [SsmParameter](/types/SsmParameter.md)
+- [Type](/types/Type.md)
+- [UserPool](/types/UserPool.md)

package/dist/okf/types/Key.md

@@ -34,3 +34,4 @@ resource_type: AWS::PaymentCryptography::Key
 
 - [WAW024](/rules/WAW024.md): Application Load Balancer does not have access logging enabled
 - [WAW043](/rules/WAW043.md): KMS customer-managed key does not have automatic key rotation enabled
+- [WAW071](/rules/WAW071.md): Tags are in the wrong property or the wrong shape for the resource type

package/dist/okf/types/Map.md

@@ -40,3 +40,4 @@ resource_type: AWS::Location::Map
 - [WAW066](/rules/WAW066.md): Private subnet's route table has no default route, or its default route targets a gateway that does not exist in the template
 - [WAW067](/rules/WAW067.md): A single-AZ NAT gateway serves private subnets across multiple Availability Zones — single point of failure for cross-AZ egress
 - [WAW068](/rules/WAW068.md): VPN Gateway or Transit Gateway has only one attached VPN Connection — no redundant path for hybrid connectivity
+- [WAW071](/rules/WAW071.md): Tags are in the wrong property or the wrong shape for the resource type

package/dist/okf/types/SsmParameter.md

@@ -24,3 +24,7 @@ resource_type: AWS::SSM::Parameter
 ## Attributes
 
 - `Arn`
+
+## Governed by
+
+- [WAW071](/rules/WAW071.md): Tags are in the wrong property or the wrong shape for the resource type

package/dist/okf/types/Type.md

@@ -83,3 +83,4 @@ resource_type: AWS::Cassandra::Type
 - [WAW066](/rules/WAW066.md): Private subnet's route table has no default route, or its default route targets a gateway that does not exist in the template
 - [WAW067](/rules/WAW067.md): A single-AZ NAT gateway serves private subnets across multiple Availability Zones — single point of failure for cross-AZ egress
 - [WAW068](/rules/WAW068.md): VPN Gateway or Transit Gateway has only one attached VPN Connection — no redundant path for hybrid connectivity
+- [WAW071](/rules/WAW071.md): Tags are in the wrong property or the wrong shape for the resource type

package/dist/okf/types/UserPool.md

@@ -59,3 +59,4 @@ resource_type: AWS::Cognito::UserPool
 - [WAW050](/rules/WAW050.md): Cognito UserPool does not have advanced security (risk-based auth) enabled
 - [WAW051](/rules/WAW051.md): Cognito UserPoolClient allows the deprecated implicit OAuth grant
 - [WAW052](/rules/WAW052.md): Cognito UserPool does not require MFA (full tier)
+- [WAW071](/rules/WAW071.md): Tags are in the wrong property or the wrong shape for the resource type

package/dist/rules/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/dist/rules/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/dist/serializer.d.ts

@@ -1,4 +1,16 @@
 import type { Serializer } from "@intentius/chant/serializer";
+import { type TagPlacement } from "./taggable.js";
+/**
+ * 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 declare function mergeTags(explicit: unknown, stamped: Array<{
+    Key: string;
+    Value: unknown;
+}>, placement: TagPlacement): unknown;
 /**
  * AWS CloudFormation serializer implementation
  */

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;AA0nBlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAgF3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA0BlG,OAAO,EAAmD,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AA0QhG;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,EAC/C,SAAS,EAAE,YAAY,GACtB,OAAO,CAcT;AAkWD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAgF3B,CAAC"}

package/dist/serializer.js

@@ -14,7 +14,7 @@ import { isMapping } from "./mapping.js";
 import { isDefaultTags } from "./default-tags.js";
 import { isTemplateTransform } from "./template-transform.js";
 import { isTemplateSection } from "./template-sections.js";
-import { loadTaggableResources } from "./taggable.js";
+import { isTagIntrinsic, loadTagPlacements, readTagValue } from "./taggable.js";
 /**
  * Check if a declarable is a CoreParameter
  */
@@ -172,6 +172,29 @@ function renderReceiptRows(receipts, ownership) {
     }
     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, stamped, placement) {
+    if (explicit !== undefined && (isTagIntrinsic(explicit) || (typeof explicit !== "object" || explicit === null))) {
+        return undefined;
+    }
+    if (placement.shape === "map") {
+        const merged = {};
+        for (const t of stamped)
+            merged[t.Key] = t.Value;
+        return { ...merged, ...readTagValue(explicit) };
+    }
+    const explicitList = Array.isArray(explicit)
+        ? explicit
+        : 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).
  */
@@ -371,22 +394,33 @@ function serializeToTemplate(entities, outputs, extraParameters, extraOutputs, o
             template.Resources[name] = resource;
         }
     }
-    // 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))
+            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 ?? []);
-            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),
+                };
+            }
         }
     }
     // Emit StackOutput entities as CF Outputs

package/dist/spec/parse.d.ts

@@ -46,11 +46,22 @@ 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 {
     resource: ParsedResource;
@@ -61,6 +72,17 @@ export interface SchemaParseResult {
  * Parse a CloudFormation Registry JSON Schema into typed structures.
  */
 export declare function parseCFNSchema(data: string | Buffer): SchemaParseResult;
+/**
+ * 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 declare function tagPlacement(schema: CFNSchema): {
+    tagProperty?: string;
+    tagShape?: TagShape;
+};
 export declare const constraintsIsEmpty: typeof coreConstraintsIsEmpty;
 /**
  * Extract short resource name: "AWS::S3::Bucket" → "Bucket"

package/dist/spec/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoC,MAAM,SAAS,CAAC;AAC3E,OAAO,EAGL,kBAAkB,IAAI,sBAAsB,EAE5C,KAAK,mBAAmB,EAIzB,MAAM,sCAAsC,CAAC;AAG9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAkBhF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAmJvE;AAiBD,eAAO,MAAM,kBAAkB,+BAAyB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AAuDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAYzE"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/spec/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAoC,MAAM,SAAS,CAAC;AAC3E,OAAO,EAGL,kBAAkB,IAAI,sBAAsB,EAE5C,KAAK,mBAAmB,EAIzB,MAAM,sCAAsC,CAAC;AAG9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAkBhF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,mBAAmB,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAClE,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAoJvE;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAe7F;AAuDD,eAAO,MAAM,kBAAkB,+BAAyB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AAuDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAYzE"}

package/dist/spec/parse.js

@@ -122,6 +122,7 @@ export function parseCFNSchema(data) {
             taggable: true,
             tagOnCreate: schema.tagging.tagOnCreate ?? false,
             tagUpdatable: schema.tagging.tagUpdatable ?? false,
+            ...tagPlacement(schema),
         };
     }
     // --- Replacement strategy ---
@@ -151,6 +152,61 @@ export function parseCFNSchema(data) {
     };
 }
 // --- 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) {
+    const pointer = schema.tagging?.tagProperty;
+    let name;
+    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 } : {};
+}
+function resolveLocalRef(value, schema) {
+    let node = value;
+    for (let i = 0; i < 8 && node && typeof node.$ref === "string"; i++) {
+        const def = refDefinitionName(node.$ref);
+        node = def ? schema.definitions?.[def] : undefined;
+    }
+    return node && typeof node === "object" ? node : undefined;
+}
+function hasType(node, t) {
+    return node.type === t || (Array.isArray(node.type) && node.type.includes(t));
+}
+function isKeyValueItem(node, schema) {
+    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, schema) {
+    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, schema) {
     const shortName = cfnShortName(schema.typeName);
     return coreResolvePropertyType(prop, schema, (defName) => `${shortName}_${defName}`);

package/dist/taggable.d.ts

@@ -3,9 +3,37 @@
  *
  * Lazy-loaded and cached for the lifetime of the process.
  */
+/** How a type's tags are written: a `[{Key, Value}]` list or a key-to-value map. */
+export type TagShape = "list" | "map";
+/** The property a type's tags live in, and its shape (#4350). */
+export interface TagPlacement {
+    property: string;
+    shape: TagShape;
+}
+/**
+ * Every taggable type, mapped to where its tags go. `null` means the schema
+ * puts the tags somewhere chant can't stamp (inside an array, or under a
+ * wrapper object), so the type gets no stamped tags.
+ */
+export declare function loadTagPlacements(): Map<string, TagPlacement | null>;
 /**
  * Load taggable resource types from the lexicon JSON.
  * Result is cached after first call.
  */
 export declare function loadTaggableResources(): Set<string>;
+/** Where `type`'s tags go, or undefined when it isn't taggable or can't be placed. */
+export declare function tagPlacementFor(type: string): TagPlacement | undefined;
+/** True for a CloudFormation intrinsic (`Ref`, `Fn::*`), which can't be merged into. */
+export declare function isTagIntrinsic(value: unknown): boolean;
+/**
+ * Read a tag value of either shape into a key-to-value map: a `[{Key, Value}]`
+ * list or a plain map. An intrinsic or anything else reads as `{}`.
+ */
+export declare function readTagValue(value: unknown): Record<string, unknown>;
+/**
+ * The tags on a resource's property tree, read through the type's own tag
+ * property (`UserPoolTags` on a Cognito user pool), falling back to `Tags`
+ * when the type is unknown. Either shape reads (#4350).
+ */
+export declare function readResourceTags(type: string | undefined, properties: Record<string, unknown> | undefined): Record<string, unknown>;
 //# sourceMappingURL=taggable.d.ts.map

package/dist/taggable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taggable.d.ts","sourceRoot":"","sources":["../src/taggable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,CAAC,CAoBnD"}
+{"version":3,"file":"taggable.d.ts","sourceRoot":"","sources":["../src/taggable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,oFAAoF;AACpF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtC,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAiBD;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC,CAoBpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,GAAG,CAAC,MAAM,CAAC,CAEnD;AAED,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEtE;AAMD,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAItD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAInI"}

package/dist/taggable.js

@@ -8,26 +8,77 @@ import { join } from "path";
 import { moduleSourceDir } from "@intentius/chant/module-source";
 let _cached;
 /**
- * Load taggable resource types from the lexicon JSON.
- * Result is cached after first call.
+ * Every taggable type, mapped to where its tags go. `null` means the schema
+ * puts the tags somewhere chant can't stamp (inside an array, or under a
+ * wrapper object), so the type gets no stamped tags.
  */
-export function loadTaggableResources() {
+export function loadTagPlacements() {
     if (_cached)
         return _cached;
-    const set = new Set();
+    const map = new Map();
     try {
         const lexiconPath = join(moduleSourceDir(import.meta.url), "generated", "lexicon-aws.json");
         const content = readFileSync(lexiconPath, "utf-8");
         const data = JSON.parse(content);
         for (const [_name, entry] of Object.entries(data)) {
-            if (entry.kind === "resource" && entry.resourceType && entry.tagging?.taggable) {
-                set.add(entry.resourceType);
-            }
+            if (entry.kind !== "resource" || !entry.resourceType || !entry.tagging?.taggable)
+                continue;
+            const { tagProperty, tagShape } = entry.tagging;
+            map.set(entry.resourceType, tagProperty && tagShape ? { property: tagProperty, shape: tagShape } : null);
         }
     }
     catch {
         // Lexicon not available — skip
     }
-    _cached = set;
-    return set;
+    _cached = map;
+    return map;
+}
+/**
+ * Load taggable resource types from the lexicon JSON.
+ * Result is cached after first call.
+ */
+export function loadTaggableResources() {
+    return new Set(loadTagPlacements().keys());
+}
+/** Where `type`'s tags go, or undefined when it isn't taggable or can't be placed. */
+export function tagPlacementFor(type) {
+    return loadTagPlacements().get(type) ?? undefined;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** True for a CloudFormation intrinsic (`Ref`, `Fn::*`), which can't be merged into. */
+export function isTagIntrinsic(value) {
+    if (!isPlainObject(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 1 && (keys[0] === "Ref" || keys[0].startsWith("Fn::"));
+}
+/**
+ * Read a tag value of either shape into a key-to-value map: a `[{Key, Value}]`
+ * list or a plain map. An intrinsic or anything else reads as `{}`.
+ */
+export function readTagValue(value) {
+    const out = {};
+    if (Array.isArray(value)) {
+        for (const t of value) {
+            if (isPlainObject(t) && typeof t.Key === "string")
+                out[t.Key] = t.Value;
+        }
+        return out;
+    }
+    if (isPlainObject(value) && !isTagIntrinsic(value))
+        return { ...value };
+    return out;
+}
+/**
+ * The tags on a resource's property tree, read through the type's own tag
+ * property (`UserPoolTags` on a Cognito user pool), falling back to `Tags`
+ * when the type is unknown. Either shape reads (#4350).
+ */
+export function readResourceTags(type, properties) {
+    if (!properties)
+        return {};
+    const placement = type ? tagPlacementFor(type) : undefined;
+    return readTagValue(properties[placement?.property ?? "Tags"]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.124.43",
+  "version": "0.124.45",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,6 +80,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.43"
+    "@intentius/chant": "^0.124.45"
   }
 }

package/src/codegen/generate-lexicon.ts

@@ -4,7 +4,7 @@
  * Output is a Record<string, LexiconEntry> keyed by generated class name.
  */
 
-import type { SchemaParseResult } from "../spec/parse";
+import type { ResourceTagging, SchemaParseResult } from "../spec/parse";
 import { cfnShortName } from "../spec/parse";
 import type { NamingStrategy } from "./naming";
 import type { ExtensionConstraint } from "./extensions";
@@ -33,7 +33,7 @@ export interface LexiconEntry {
   inferredDeprecations?: string[];
   conditionalCreateOnly?: string[];
   replacementStrategy?: "delete_then_create" | "create_then_delete";
-  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
+  tagging?: ResourceTagging;
   runtimeDeprecations?: Record<string, string>;
 }
 

package/src/deep-observe.test.ts

@@ -353,6 +353,25 @@ describe("hasOwnershipMarker", () => {
     expect(hasOwnershipMarker({ Tags: [{ Key: "env", Value: "prod" }] })).toBe(false);
     expect(hasOwnershipMarker({})).toBe(false);
   });
+
+  test("reads a map, and the type's own tag property (#4350)", () => {
+    expect(hasOwnershipMarker({ Tags: { "chant:managed-by": "chant" } }, "AWS::SSM::Parameter")).toBe(true);
+    expect(hasOwnershipMarker({ UserPoolTags: { "chant:managed-by": "chant" } }, "AWS::Cognito::UserPool")).toBe(true);
+    expect(hasOwnershipMarker({ Tags: { "chant:managed-by": "chant" } }, "AWS::Cognito::UserPool")).toBe(false);
+  });
+
+  test("prunes the live map entry of the marker on a map-tagged type (#4350)", () => {
+    const out = normalizeDeepProperties(
+      { UserPoolTags: { "chant:managed-by": "chant", team: "a" } },
+      {
+        entityType: "AWS::Cognito::UserPool",
+        side: "live",
+        hooks: awsDeepNormalizationHooks,
+        counterpartPaths: new Set<string>(),
+      },
+    );
+    expect(out).toEqual({ UserPoolTags: { team: "a" } });
+  });
 });
 
 describe("observeResourcesDeepAws", () => {

package/src/deep-observe.ts

@@ -63,6 +63,7 @@ import {
 } from "./api/read-client";
 import { declaredIdentifier } from "./identity-observe";
 import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+import { readResourceTags, tagPlacementFor } from "./taggable";
 import {
   AWS_DEEP_BLIND_SPOTS,
   EC2_TOPOLOGY_GENERATED_NAMES,
@@ -409,6 +410,8 @@ export const awsDeepNormalizationHooks: DeepNormalizationHooks = {
     // drift. Counterpart-gated, so a template that declares the tag itself is
     // still compared against what is live.
     if (isOwnershipTag(node.value)) return true;
+    // The same marker as a map entry, on a map-tagged type (#4350).
+    if (OWNERSHIP_TAG_KEYS.has(node.key) && isMapTagEntry(node.entityType, node.pattern, node.key)) return true;
 
     // A name the service generated because source did not supply one.
     if (AWS_GENERATED_NAMES[node.entityType]?.has(node.pattern)) return true;
@@ -533,11 +536,19 @@ function isOwnershipTag(value: unknown): boolean {
   return isRecord(value) && typeof value.Key === "string" && OWNERSHIP_TAG_KEYS.has(value.Key);
 }
 
-/** True when the live property tree carries chant's ownership marker tag. */
-export function hasOwnershipMarker(properties: Record<string, unknown>): boolean {
-  const tags = properties.Tags;
-  if (!Array.isArray(tags)) return false;
-  return tags.some((t) => isRecord(t) && t.Key === AWS_TAG_OWNERSHIP_KEYS.managedBy);
+/** True when `pattern` is `<tagProperty>.<key>` on a type whose tags are a map. */
+function isMapTagEntry(type: string, pattern: string, key: string): boolean {
+  const placement = tagPlacementFor(type);
+  return placement?.shape === "map" && pattern === `${placement.property}.${key}`;
+}
+
+/**
+ * True when the live property tree carries chant's ownership marker tag. With
+ * a `type`, the tags are read from that type's own tag property
+ * (`UserPoolTags`); either way a list or a map reads (#4350).
+ */
+export function hasOwnershipMarker(properties: Record<string, unknown>, type?: string): boolean {
+  return readResourceTags(type, properties)[AWS_TAG_OWNERSHIP_KEYS.managedBy] !== undefined;
 }
 
 export interface AwsDeepObserveOptions {
@@ -680,7 +691,7 @@ export async function observeResourcesDeepAws(
     // thin path this one can answer the ownership question (#1015's open note).
     // A resource withheld by the filter is `filtered`, never absent: it exists,
     // it just isn't chant's.
-    const owned = hasOwnershipMarker(properties);
+    const owned = hasOwnershipMarker(properties, type);
     if (options.owned && !owned) {
       unobserved[entityName] = {
         type,