feat(loader): warn on enum vocabularies ambiguous under @normalize: strip (cross-port)

@normalize: strip -- the DEFAULT -- upper-cases and keeps only [A-Z0-9]. That
erasure is what lets "SOCIAL-ATTACK" match the member SOCIAL_ATTACK, which is
desired. It also means a DELIMITED value collapses into one token, so where a
vocabulary contains a member equal to the concatenation of others, a stray
delimited value coerces SUCCESSFULLY to the wrong member:

  values = {READ, WRITE, READWRITE};  input "read|write"  ->  READWRITE

The field is reported EXTRACTED, not MALFORMED -- a plausible wrong value that
anything branching on field state will trust. Proven against the real coercion
path before writing the guard; the control case "friendly|hostile" against
{FRIENDLY, HOSTILE} correctly returns MALFORMED, which isolates the hazard to
concatenation-collision vocabularies.

It cannot be fixed at coercion time: "read-write" legitimately means READWRITE,
so the two readings are indistinguishable from the value alone. But the collision
IS detectable from metadata, so all four loaders now warn the author at
declaration time -- WARN_ENUM_NORMALIZE_AMBIGUOUS -- when a field.enum's own
@values contains a member that word-breaks into two or more other members and the
effective mode is strip. `collapse` is immune (folds only [\s_-]+, so a "|"
survives and the value fails cleanly) and is the documented fix.

Design notes:
- WARNING, never an error: such a vocabulary is legal and completely unambiguous
  for exact matching, and the author may have no delimited input at all.
- Word-break (DP), not a pairwise scan, so A + B + C == ABC is caught too.
  Deterministic, since every port must produce the identical warning.
- Own-@values only: warns once at the declaring node, not on every field that
  extends it. Self excluded BY INDEX, not by value -- two distinct members can
  strip to the same string, which is a separate (duplicate) concern.
- Mode-gated: collapse/none are structurally immune and are skipped.

Cross-port: TS reference + Java + Python + C# (Kotlin inherits the JVM loader),
gated by the shared warning-enum-normalize-ambiguous conformance fixture. A scan
of all 54 @values sets in the corpus found zero pre-existing collisions, so no
existing fixture changes and no generated output changes.

Also records in the extract KNOWN_GAPS that splitting a delimited scalar into
array elements (a @delimiter attr) is intentionally NOT offered, with the prior
art and the ADR-0037 step-0 reasoning, so it does not get re-litigated. The
supported shape is repeated elements / a JSON array + field.enum isArray: true.

Suites: TS metadata 2278, Python 1637, Java metadata 1279, C# conformance 836 +
render 290 + codegen 339 + cli 46 -- all green.

Author: dmealing

CHANGELOG.md

@@ -10,6 +10,35 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 **npm** — `metadata` + `codegen-ts`; **Maven Central** — `maven-plugin`; PyPI / NuGet
 unchanged.
 
+### Added — `WARN_ENUM_NORMALIZE_AMBIGUOUS`, an authoring guard for a silent enum mis-extraction
+
+`@normalize: strip` — the **default** — upper-cases and keeps only `[A-Z0-9]`, which is what lets
+`"SOCIAL-ATTACK"` match the member `SOCIAL_ATTACK`. The same erasure means a *delimited* value
+collapses into a single token, so where a vocabulary contains a member equal to the concatenation of
+others, a stray delimited value coerces **successfully** to the wrong member:
+
+```
+values = {READ, WRITE, READWRITE};  input "read|write"  ->  READWRITE
+```
+
+The field is reported `EXTRACTED`, not `MALFORMED` — a plausible, wrong value that anything
+branching on field state will trust. It cannot be fixed at coercion time (`"read-write"`
+legitimately means `READWRITE`, so the two readings are indistinguishable from the value alone), but
+the collision **is** detectable from metadata. All four loaders now warn at declaration time when a
+`field.enum`'s own `@values` contains a member that word-breaks into two or more other members and
+the effective mode is `strip`. `collapse` is immune — it folds only `[\s_-]+`, so a `|` survives and
+the value fails cleanly — and is the documented fix for a field that can receive delimited input.
+
+Advisory, never an error: such a vocabulary is legal and completely unambiguous for exact matching.
+Detection is word-break (not pairwise), so three-way collisions are caught; the warning fires once at
+the declaring node rather than on every field that `extends` it. Cross-port, gated by the shared
+`warning-enum-normalize-ambiguous` conformance fixture (TS / Java / Python / C#; Kotlin inherits the
+JVM loader). No existing fixture in the corpus collides, and no generated output changes.
+
+Also recorded in the extract engine's `KNOWN_GAPS.md`: splitting a delimited scalar into array
+elements (a `@delimiter` attribute) is **intentionally not offered** — the supported way to express a
+multi-valued response field is repeated elements / a JSON array plus `field.enum` + `isArray: true`.
+
 ### Fixed — a shared `enums.ts` no longer collides across `entityFile()` instances (#266)
 
 Declaring a root-level abstract `field.enum` made **every** `entityFile()` instance emit

fixtures/conformance/warning-enum-normalize-ambiguous/expected-errors.json

@@ -0,0 +1,15 @@
+{
+  "errors": [],
+  "warnings": [
+    {
+      "code": "WARN_ENUM_NORMALIZE_AMBIGUOUS",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.access.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[0]['field.enum']"
+      }
+    }
+  ]
+}

fixtures/conformance/warning-enum-normalize-ambiguous/expected.json

@@ -0,0 +1,19 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "field.enum": {
+          "name": "Access",
+          "package": "acme",
+          "abstract": true,
+          "@values": [
+            "READ",
+            "WRITE",
+            "READWRITE"
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/warning-enum-normalize-ambiguous/input/meta.access.json

@@ -0,0 +1,18 @@
+{
+  "metadata.root": {
+    "package": "acme",
+    "children": [
+      {
+        "field.enum": {
+          "name": "Access",
+          "abstract": true,
+          "@values": [
+            "READ",
+            "WRITE",
+            "READWRITE"
+          ]
+        }
+      }
+    ]
+  }
+}

server/csharp/MetaObjects/Errors.cs

@@ -224,6 +224,16 @@ public static class WarningCodes
     /// across different sources.
     /// </summary>
     public const string WARN_ORIGIN_UNDER_UNMANAGED = "WARN_ORIGIN_UNDER_UNMANAGED";
+
+    /// <summary>
+    /// A field.enum whose @values contains a member equal to the concatenation of two or
+    /// more OTHER members once <c>strip</c>-normalized (the default mode erases separators).
+    /// A delimited value then collapses into that member and coerces SUCCESSFULLY — reported
+    /// EXTRACTED with a wrong-but-valid value rather than MALFORMED. Advisory: such a
+    /// vocabulary is legal and unambiguous for exact matching; <c>@normalize: collapse</c>
+    /// is the fix when delimited input is possible.
+    /// </summary>
+    public const string WARN_ENUM_NORMALIZE_AMBIGUOUS = "WARN_ENUM_NORMALIZE_AMBIGUOUS";
 }
 
 /// <summary>

server/csharp/MetaObjects/Loader/MetaDataLoader.cs

@@ -566,6 +566,18 @@ public LoadResult Load(IReadOnlyList<IMetaDataSource> sources)
                 }
             }
 
+            // Authoring guard: a field.enum vocabulary ambiguous under the default
+            // @normalize: strip. WARN_ENUM_NORMALIZE_AMBIGUOUS.
+            var enumAmbiguity = ValidationPasses.ValidateEnumNormalizeAmbiguity(root);
+            if (enumAmbiguity.Count > 0)
+            {
+                envelopeWarnings.AddRange(enumAmbiguity);
+                foreach (var w in enumAmbiguity)
+                {
+                    warnings.Add(w.Message);
+                }
+            }
+
             // FR-014: TPH discriminator cross-attribute rules.
             errors.AddRange(ValidationPasses.ValidateDiscriminator(root));
 

server/csharp/MetaObjects/Loader/ValidationPasses.cs

@@ -2960,6 +2960,135 @@ public static IReadOnlyList<MetaError> ValidateTemplatePayloadRefs(MetaData root
         return errors.AsReadOnly();
     }
 
+    // =========================================================================
+    // Authoring guard — enum vocabularies ambiguous under @normalize: strip.
+    //   WARN_ENUM_NORMALIZE_AMBIGUOUS
+    // Mirrors TS core/field/validate-enum-normalize-ambiguity.ts.
+    //
+    // `strip` (the DEFAULT) upper-cases and keeps only [A-Z0-9], erasing every
+    // separator. That is what makes "SOCIAL-ATTACK" match SOCIAL_ATTACK — desired.
+    // But it also collapses a DELIMITED value into one token, and if that token
+    // equals another member the extract engine coerces it SUCCESSFULLY:
+    //   values = {READ, WRITE, READWRITE};  input "read|write"  ->  READWRITE
+    // reported EXTRACTED, not MALFORMED — a plausible wrong value.
+    //
+    // WARNING, not error: such a vocabulary is legal and unambiguous for exact
+    // matching. `collapse` folds only [\s_-]+ and `none` folds nothing, so neither
+    // can merge tokens across a delimiter like "|" — both are skipped.
+    // =========================================================================
+
+    /// <summary>`strip` normalization: ASCII upper-case, then keep only [A-Z0-9]. Mirrors Normalize.STRIP.</summary>
+    private static string StripNormalize(string s)
+    {
+        var sb = new System.Text.StringBuilder(s.Length);
+        foreach (var ch in s.ToUpperInvariant())
+        {
+            if ((ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9')) sb.Append(ch);
+        }
+        return sb.ToString();
+    }
+
+    /// <summary>
+    /// Word-break: can <paramref name="target"/> be segmented into two or more dictionary
+    /// entries? Returns the member names in order, or null. Word-break rather than a pairwise
+    /// scan so a three-way collision (A + B + C == ABC) is caught too.
+    /// </summary>
+    private static List<string>? SegmentInto(string target, List<(string Member, string Stripped)> dict)
+    {
+        int n = target.Length;
+        var best = new List<string>?[n + 1];
+        best[0] = new List<string>();
+        for (int i = 0; i < n; i++)
+        {
+            var prefix = best[i];
+            if (prefix is null) continue;
+            foreach (var (member, stripped) in dict)
+            {
+                int end = i + stripped.Length;
+                if (end > n || string.CompareOrdinal(target, i, stripped, 0, stripped.Length) != 0) continue;
+                var cand = new List<string>(prefix) { member };
+                var cur = best[end];
+                if (cur is null || cand.Count < cur.Count) best[end] = cand;
+            }
+        }
+        var full = best[n];
+        // Two or more segments: a single-segment match is just another member that strips
+        // to the same string — a different (duplicate) concern.
+        return (full is not null && full.Count >= 2) ? full : null;
+    }
+
+    /// <summary>Effective @normalize for an enum field: own/inherited → owning object → default.</summary>
+    private static string EffectiveNormalizeMode(MetaData field)
+    {
+        // ADR-0039: resolving accessor — an enum extending an abstract enum must see the
+        // super's @normalize.
+        if (field.Attr(FIELD_ATTR_NORMALIZE) is string own) return own;
+        var parent = field.Parent;
+        if (parent is not null && parent.Type == TYPE_OBJECT
+            && parent.Attr(FIELD_ATTR_NORMALIZE) is string objMode)
+        {
+            return objMode;
+        }
+        return NORMALIZE_DEFAULT;
+    }
+
+    public static IReadOnlyList<LoaderWarning> ValidateEnumNormalizeAmbiguity(MetaData root)
+    {
+        var warnings = new List<LoaderWarning>();
+        VisitEnumNormalizeAmbiguity(root, warnings);
+        return warnings;
+    }
+
+    private static void VisitEnumNormalizeAmbiguity(MetaData node, List<LoaderWarning> warnings)
+    {
+        if (node.Type == TYPE_FIELD && node.SubType == FIELD_SUBTYPE_ENUM)
+        {
+            // ADR-0039 sanctioned own: check the vocabulary DECLARED here. A concrete enum
+            // inheriting @values shares the super's member set, already checked at the super —
+            // one hazard yields one warning, not one per referring field.
+            if (node.OwnAttr(FIELD_ATTR_VALUES) is System.Collections.IEnumerable rawEnum
+                && node.OwnAttr(FIELD_ATTR_VALUES) is not string)
+            {
+                var members = new List<string>();
+                foreach (var o in rawEnum) members.Add(o?.ToString() ?? string.Empty);
+                if (members.Count > 1
+                    && EffectiveNormalizeMode(node) == NORMALIZE_DEFAULT)
+                {
+                    var entries = members.Select(m => (Member: m, Stripped: StripNormalize(m))).ToList();
+                    for (int i = 0; i < entries.Count; i++)
+                    {
+                        var self = entries[i];
+                        if (self.Stripped.Length == 0) continue; // e.g. "_" — nothing to collide with
+                        // Exclude self BY INDEX, not by value: two distinct members can strip
+                        // to the same string, which is a separate (duplicate) concern.
+                        var others = entries.Where((_, j) => j != i)
+                                            .Where(e => e.Stripped.Length > 0).ToList();
+                        var seg = SegmentInto(self.Stripped, others);
+                        if (seg is not null)
+                        {
+                            var plus = string.Join(" + ", seg.Select(s => $"'{s}'"));
+                            var delimited = string.Join("|", seg.Select(s => s.ToLowerInvariant()));
+                            warnings.Add(new LoaderWarning(
+                                Code: WarningCodes.WARN_ENUM_NORMALIZE_AMBIGUOUS,
+                                Message:
+                                    $"field.enum \"{node.Name}\" member '{self.Member}' is the " +
+                                    $"concatenation of {plus} under @{FIELD_ATTR_NORMALIZE}: " +
+                                    $"'{NORMALIZE_DEFAULT}' (the default), which erases " +
+                                    $"separators. A delimited value such as \"{delimited}\" would coerce " +
+                                    $"silently to '{self.Member}' and be reported as extracted rather " +
+                                    $"than malformed. Set @{FIELD_ATTR_NORMALIZE}: " +
+                                    "'collapse' on this field if it can receive delimited input.",
+                                Source: node.Source));
+                            break; // one warning per declaring node
+                        }
+                    }
+                }
+            }
+        }
+        // ADR-0039 sanctioned own: structural walk of what each node declares.
+        foreach (var child in node.OwnChildren()) VisitEnumNormalizeAmbiguity(child, warnings);
+    }
+
     // =========================================================================
     // FR-013 — field-level @readOnly cross-attribute rules.
     //   ERR_READONLY_ASSIGNED_PRIMARY / ERR_READONLY_DOWNGRADE / WARN_READONLY_VALUE_OBJECT