feat(codegen-csharp): FR-019 — bind @provided enum namespace to declaring package

A @provided shared enum's C# namespace now resolves from the enum's declaring
metadata package via GenConfig.PackageNamespaces (package→namespace), with the
single ProvidedEnumNamespace as a fallback. SharedEnum carries its declaring
package; SharedEnumTypeReference resolves package-first and, when unresolved,
errors naming the enum AND its package.

Why: an adopter with N external enums across M namespaces now configures M
package entries (one per namespace) instead of N per-enum entries, and adding an
enum to an already-mapped package needs no config change. The package is
metadata-native; only the binding is per-port config (ADR-0001) — mirroring how
every generated type relates to its package.

- GenConfig.PackageNamespaces (Dictionary<package, namespace>)
- Fr019SharedEnum: SharedEnum.Package + PackageOf(decl) + package-first resolution
- 4 new codegen tests (package resolve / map precedence / fallback / error names package)
- ADR-0026 §3 + FR-019 spec + C# codegen skill: record the package-binding model

Codegen.Tests 187/0 (drift gate green); solution builds clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

agent-context/skills/metaobjects-codegen/references/csharp.md

@@ -69,6 +69,17 @@ plus finer hooks — `EmitClassHeader` / `EmitClassDeclarationLine` (class decla
 generator and override only the seam you need rather than forking. `@default` on a
 scalar emits a literal initializer; an `object.value`'s default storage is jsonb.
 
+**Shared + externally-provided enums (FR-019).** A package-level abstract
+`field.enum` (`abstract: true`, `@values`) extended by concrete entity fields is
+materialized **once** (`Enums.g.cs`) and referenced — no per-entity nested enum.
+Adding `@provided: true` to that declaration suppresses materialization entirely:
+consuming fields reference a hand-written/third-party enum, and the C# namespace
+**binds to the enum's declaring metadata package** via
+`GenConfig.PackageNamespaces["<pkg>"] = "Your.Namespace"` (one entry per namespace;
+`ProvidedEnumNamespace` is the single fallback). The `@values` still drive the DB
+`CHECK` + validation. This replaces the retired C#-only `@csEnumType` FQN attr
+(ADR-0026) — no language FQN ever lives in metadata (ADR-0001).
+
 ## Re-scaffold this context
 
 `dotnet meta agent-docs --server csharp [--out <dir>]` (re)scaffolds the slim

docs/superpowers/specs/2026-06-06-fr-019-shared-and-provided-enums-design.md

@@ -75,10 +75,22 @@ values `[…]`**, materialize ONE standalone type and reference it from consumer
 
 For **`@provided: true`**: materialize **nothing** for `E`; each consuming field
 references `E` resolved to the port's configured namespace/package + `E` (C#
-`<cfg.enumNamespace>.E`, Kotlin/Java `<cfg.enumPackage>.E`, Python an import of
-`E` from `<cfg.enumModule>`, TS an import of `E`). A missing config for a
-referenced `@provided` enum is a **codegen-time error** (clear message naming the
-enum + the config key), not a metadata error.
+`<ns>.E`, Kotlin/Java `<pkg>.E`, Python an import of `E` from `<module>`, TS an
+import of `E`). The namespace **binds to `E`'s declaring metadata package** via a
+per-port **package→namespace map** (C# `GenConfig.PackageNamespaces`, keyed by the
+metadata package `E` is declared under), with a single
+`ProvidedEnumNamespace`/`enumNamespace` **fallback** for the one-namespace case.
+This keeps config proportional to the number of namespaces (one entry per package),
+not the number of enums, and mirrors how every generated type relates to its
+package (ADR-0001 — the package is metadata; only the binding is config). A
+referenced `@provided` enum whose package resolves to no namespace (no map entry
+**and** no fallback) is a **codegen-time error** naming the enum + its package, not
+a metadata error.
+
+> **C# status:** shipped — `GenConfig.PackageNamespaces` (package→namespace) with
+> the `ProvidedEnumNamespace` fallback; `SharedEnum` carries its declaring package;
+> `Fr019SharedEnum.SharedEnumTypeReference` resolves package-first. The other ports
+> adopt the same package-binding shape during graduation.
 
 **Byte-identical default:** an enum that is NOT a package-level shared/abstract
 enum (the common inline case) emits exactly as today — the per-entity nested

server/csharp/MetaObjects.Codegen.Tests/Fr019SharedEnumCodegenTests.cs

@@ -28,7 +28,18 @@ private static MetaRoot Load(string json)
         return r.Root;
     }
 
-    private static GenContext Ctx(MetaRoot root, string? providedNs = null) => new()
+    private static MetaRoot LoadMany(params string[] jsons)
+    {
+        var srcs = jsons.Select((j, i) => (IMetaDataSource)new InMemoryStringSource(j, id: $"fr019-{i}.json")).ToList();
+        var r = new MetaDataLoader().Load(srcs);
+        Assert.Empty(r.Errors);
+        return r.Root;
+    }
+
+    private static GenContext Ctx(
+        MetaRoot root,
+        string? providedNs = null,
+        Dictionary<string, string>? packageNamespaces = null) => new()
     {
         Entities = root.Objects(),
         Root = root,
@@ -37,6 +48,7 @@ private static MetaRoot Load(string json)
             OutDir = "/tmp",
             Namespace = "Acme.Generated",
             ProvidedEnumNamespace = providedNs,
+            PackageNamespaces = packageNamespaces ?? new(),
         },
     };
 
@@ -140,6 +152,76 @@ public void Provided_enum_without_configured_namespace_is_a_codegen_error()
         Assert.Contains("ProvidedEnumNamespace", ex.Message);
     }
 
+    // ── FR-019 (package-binding) — a @provided enum's namespace maps to its declaring
+    //    metadata package via GenConfig.PackageNamespaces, NOT a single global namespace.
+    //    The package is metadata-native (ADR-0001); the package→C# namespace map is
+    //    per-port codegen config. This lets one model reference provided enums living in
+    //    several namespaces (the multi-namespace adopter shape). ──
+
+    private const string ExtEnumSrc = """
+    { "metadata.root": { "package": "acme::ext::auth", "children": [
+      { "field.enum": { "name": "ContactMethod", "abstract": true, "@values": ["EMAIL", "PHONE"], "@provided": true } }
+    ]}}
+    """;
+    private const string ExtConsumerSrc = """
+    { "metadata.root": { "package": "acme", "children": [
+      { "object.entity": { "name": "Customer", "children": [
+        { "source.rdb": { "@table": "customers" } },
+        { "field.long": { "name": "id" } },
+        { "field.enum": { "name": "preferred", "extends": "acme::ext::auth::ContactMethod" } },
+        { "identity.primary": { "@fields": "id" } }
+      ]}}
+    ]}}
+    """;
+
+    [Fact]
+    public void Provided_enum_namespace_resolves_from_its_declaring_package()
+    {
+        var root = LoadMany(ExtEnumSrc, ExtConsumerSrc);
+        var files = new EntityGenerator().Generate(
+            Ctx(root, packageNamespaces: new() { ["acme::ext::auth"] = "Acme.External.Auth" })).ToList();
+
+        Assert.DoesNotContain(files, f => f.Path == "Enums.g.cs");
+        var customer = Assert.Single(files, f => f.Path == "Customer.g.cs");
+        Assert.Contains("public Acme.External.Auth.ContactMethod? Preferred { get; set; }", customer.Content);
+    }
+
+    [Fact]
+    public void Package_namespace_map_takes_precedence_over_the_single_fallback()
+    {
+        var root = LoadMany(ExtEnumSrc, ExtConsumerSrc);
+        var files = new EntityGenerator().Generate(
+            Ctx(root,
+                providedNs: "Acme.Fallback",
+                packageNamespaces: new() { ["acme::ext::auth"] = "Acme.External.Auth" })).ToList();
+
+        var customer = Assert.Single(files, f => f.Path == "Customer.g.cs");
+        Assert.Contains("public Acme.External.Auth.ContactMethod? Preferred { get; set; }", customer.Content);
+        Assert.DoesNotContain("Acme.Fallback", customer.Content);
+    }
+
+    [Fact]
+    public void Single_namespace_fallback_applies_when_package_is_unmapped()
+    {
+        var root = LoadMany(ExtEnumSrc, ExtConsumerSrc);
+        var files = new EntityGenerator().Generate(
+            Ctx(root, providedNs: "Acme.Fallback")).ToList(); // no PackageNamespaces entry
+
+        var customer = Assert.Single(files, f => f.Path == "Customer.g.cs");
+        Assert.Contains("public Acme.Fallback.ContactMethod? Preferred { get; set; }", customer.Content);
+    }
+
+    [Fact]
+    public void Provided_enum_with_no_package_mapping_and_no_fallback_names_the_package()
+    {
+        var root = LoadMany(ExtEnumSrc, ExtConsumerSrc);
+        var ex = Assert.Throws<InvalidOperationException>(() =>
+            new EntityGenerator().Generate(Ctx(root)).ToList());
+
+        Assert.Contains("ContactMethod", ex.Message);
+        Assert.Contains("acme::ext::auth", ex.Message); // the declaring package, to guide the config
+    }
+
     [Fact]
     public void Inline_enum_still_emits_nested_declaration_unchanged()
     {

server/csharp/MetaObjects.Codegen/Generator.cs

@@ -44,6 +44,18 @@ public sealed record GenConfig
     /// codegen-time error naming the enum + this key.
     /// </summary>
     public string? ProvidedEnumNamespace { get; init; }
+
+    /// <summary>
+    /// FR-019 — maps a metadata <b>package</b> (e.g. <c>acme::ext::auth</c>) to the C#
+    /// namespace its <c>@provided</c> shared enums are referenced from. The namespace
+    /// binds to the enum's <i>declaring package</i> (metadata-native, ADR-0001); the
+    /// package→namespace map is per-port codegen config. This lets a single model
+    /// reference <c>@provided</c> enums that live in several namespaces (one entry per
+    /// namespace, not per enum). When a referenced provided enum's package has no entry
+    /// here, <see cref="ProvidedEnumNamespace"/> is used as the single fallback; if
+    /// neither resolves, it is a codegen-time error naming the enum + its package.
+    /// </summary>
+    public Dictionary<string, string> PackageNamespaces { get; init; } = new();
 }
 
 /// <summary>Per-run state handed to every generator.</summary>

server/csharp/MetaObjects.Codegen/Generators/Fr019SharedEnum.cs

@@ -28,8 +28,12 @@
 
 namespace MetaObjects.Codegen.Generators;
 
-/// <summary>A shared (root-level abstract) enum declaration codegen must reason about.</summary>
-public sealed record SharedEnum(string Name, IReadOnlyList<string> Values, bool Provided);
+/// <summary>A shared (root-level abstract) enum declaration codegen must reason about.
+/// <paramref name="Package"/> is the declaration's effective metadata package (folded
+/// file-default package), used to resolve a <c>@provided</c> enum's C# namespace via
+/// <see cref="GenConfig.PackageNamespaces"/> (ADR-0001: bind the namespace to the
+/// metadata package, never an FQN in metadata).</summary>
+public sealed record SharedEnum(string Name, IReadOnlyList<string> Values, bool Provided, string Package);
 
 /// <summary>
 /// FR-019 — resolves the shared/provided status of an enum field and collects the
@@ -63,7 +67,20 @@ public static class Fr019SharedEnum
         return new SharedEnum(
             Name: CSharpNaming.Pascal(decl.Name),
             Values: values,
-            Provided: decl.OwnAttr(FIELD_ATTR_PROVIDED) is true);
+            Provided: decl.OwnAttr(FIELD_ATTR_PROVIDED) is true,
+            Package: PackageOf(decl));
+    }
+
+    /// <summary>
+    /// The declaration's effective metadata package — its package-folded
+    /// <see cref="MetaData.ResolutionKey"/> with the trailing <c>::Name</c> stripped.
+    /// Empty string when the declaration carries no package (root-level, no file default).
+    /// </summary>
+    private static string PackageOf(MetaField decl)
+    {
+        var key = decl.ResolutionKey();
+        var idx = key.LastIndexOf(Structural.PACKAGE_SEPARATOR, StringComparison.Ordinal);
+        return idx < 0 ? "" : key[..idx];
     }
 
     /// <summary>
@@ -100,12 +117,17 @@ public static IReadOnlyList<SharedEnum> MaterializedSharedEnums(MetaRoot root) =
     public static string SharedEnumTypeReference(SharedEnum shared, GenConfig config)
     {
         if (!shared.Provided) return shared.Name;
-        var ns = config.ProvidedEnumNamespace;
+        // Bind the namespace to the enum's declaring metadata package (ADR-0001):
+        // PackageNamespaces[pkg] first, then the single ProvidedEnumNamespace fallback.
+        var ns = config.PackageNamespaces.TryGetValue(shared.Package, out var mapped) && !string.IsNullOrEmpty(mapped)
+            ? mapped
+            : config.ProvidedEnumNamespace;
         if (string.IsNullOrEmpty(ns))
             throw new InvalidOperationException(
-                $"provided enum \"{shared.Name}\" is marked @provided but no namespace is configured " +
-                $"to reference it from. Set \"ProvidedEnumNamespace\" in your codegen config (e.g. " +
-                $"ProvidedEnumNamespace = \"YourApp.Enums\") so the generated code can reference \"{shared.Name}\".");
+                $"provided enum \"{shared.Name}\" (declared in package \"{shared.Package}\") is marked " +
+                $"@provided but no C# namespace is configured to reference it from. Map its package in your " +
+                $"codegen config — PackageNamespaces[\"{shared.Package}\"] = \"YourApp.Enums\" — or set the " +
+                $"single ProvidedEnumNamespace fallback, so the generated code can reference \"{shared.Name}\".");
         return $"{ns}.{shared.Name}";
     }
 }

spec/decisions/ADR-0026-shared-and-provided-named-types.md

@@ -81,6 +81,18 @@ resolves to is **codegen config** per port, never a metadata attr. `@csEnumType`
 (FQN-in-metadata, on the field) is **rejected and removed** from the adopter
 surface.
 
+The namespace **binds to the type's declaring metadata package**, not to the
+individual type. A `@provided` enum declared under `package: acme::ext::auth`
+resolves its namespace from a per-port **package→namespace map** (C#:
+`GenConfig.PackageNamespaces["acme::ext::auth"] = "Acme.External.Auth"`), so an
+adopter with N external enums spread across M namespaces configures M package
+entries, not N per-type entries — and adding an enum to an already-mapped package
+needs no config change. A single fallback (`ProvidedEnumNamespace`) covers the
+common one-namespace case; an unresolved package is a codegen-time error naming
+the enum **and its package**. The package is metadata-native; only the
+package→namespace binding is per-port config — consistent with how every other
+generated type relates to its package.
+
 ### 4. Migration path (enum reuse vocabulary)
 
 Shared enums use the existing D6 abstract-`field.enum` + `extends` vocabulary