fix(loader): exempt abstract nodes from the required-attr check (#236)

The generic required-attr check flagged an ABSTRACT node for a missing required attr, so an
abstract `template.prompt` that hoists shared children but leaves `@payloadRef` to its concrete
subtypes (or to `extends`) failed to load — forcing every concrete prompt to restate it. An
abstract is a template, not an instantiated node, so it is now exempt; enforcement stays at the
concrete level (a concrete node's RESOLVING attr set must still satisfy the requirement — a
concrete missing @payloadRef, inherited or own, still errors ERR_MISSING_REQUIRED_ATTR).

All four loader ports already read the resolving set for this check (so a concrete inheriting
via extends was already satisfied); the #236 diagnosis ("own-only") was slightly off — the real
gap was the abstract exemption. Fixed identically in TS/Java/Python/C# (Kotlin inherits the JVM
loader); consistent with ADR-0039. Gated by the abstract-template-prompt-hoists-payloadref
conformance fixture (254 metamodel fixtures; TS/Java/Python/C# green) + TS unit tests
(abstract-omits loads; concrete-inherits loads; concrete-missing still errors).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014xy8powhHYJ6gfFt9Ut8dL

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,19 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed — an abstract `template.prompt` may omit a required `@payloadRef` (#236)
+
+**Cross-port** (loader — TS / Java / Python / C#; Kotlin inherits the JVM loader). The generic
+required-attr check flagged an **abstract** node for a missing required attr, so an abstract
+`template.prompt` that hoists shared children but leaves `@payloadRef` to its concrete subtypes
+(or to `extends`) failed to load — forcing every concrete prompt to restate it. An abstract is
+a template, not an instantiated node, so it's now **exempt** from the required-attr check;
+enforcement stays at the concrete level (a concrete node's resolving attr set must still satisfy
+the requirement — a concrete missing `@payloadRef`, inherited or own, still errors
+`ERR_MISSING_REQUIRED_ATTR`). Consistent with ADR-0039 (all four ports already read the
+resolving set for this check; the fix is the abstract exemption). Gated by the
+`abstract-template-prompt-hoists-payloadref` conformance fixture across all four ports.
+
 ### Fixed — empty-string column `@default: ""` no longer drifts on sqlite/d1 (#235)
 
 **npm-only** (`migrate-ts`). `buildExpectedSchema` dropped an empty-string default with a

CLAUDE.md

@@ -30,7 +30,7 @@ _Last refreshed 2026-07-26._
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
 **Cross-port conformance corpora** (every port runs the shared corpus):
-- Metamodel: `fixtures/conformance/` (253 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
+- Metamodel: `fixtures/conformance/` (254 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
 - Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
 - Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed.

docs/CONFORMANCE.md

@@ -25,7 +25,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l`.
 
 | Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
 |---|---|---|---|---|---|---|
-| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 253 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
+| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 254 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
 | [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 15 | 15 / 15 | 14 / 15 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 14 / 15 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 15 / 15 |
 | [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 31 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
 | [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -69,7 +69,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
 
 ## Fixture-to-doc mapping
 
-### `fixtures/conformance/` — metamodel loader + canonical serializer (253)
+### `fixtures/conformance/` — metamodel loader + canonical serializer (254)
 
 | Fixture prefix | Feature doc |
 |---|---|
@@ -139,7 +139,7 @@ the port's own GENERATED API artifact booted over HTTP.
 
 ## Orphaned fixtures (tested but not yet documented)
 
-The fixtures in the six corpora mapped above (metamodel 253 + yaml 15 + verify 31
+The fixtures in the six corpora mapped above (metamodel 254 + yaml 15 + verify 31
 + render 15 + persistence 30 + api-contract 41) each map to a feature doc. None
 are orphaned today. The remaining corpora in the totals table gate tooling
 contracts (registry manifests, provider composition, agent context, docs emit)

fixtures/conformance/abstract-template-prompt-hoists-payloadref/expected.json

@@ -0,0 +1,35 @@
+{
+  "metadata.root": {
+    "package": "acme::ai",
+    "children": [
+      {
+        "object.value": {
+          "name": "AuthorBrief",
+          "children": [
+            {
+              "field.string": {
+                "name": "displayName"
+              }
+            }
+          ]
+        }
+      },
+      {
+        "template.prompt": {
+          "name": "BasePrompt",
+          "abstract": true,
+          "@format": "xml",
+          "@textRef": "prompt/base"
+        }
+      },
+      {
+        "template.prompt": {
+          "name": "ConcretePrompt",
+          "extends": "acme::ai::BasePrompt",
+          "@payloadRef": "acme::ai::AuthorBrief",
+          "@textRef": "prompt/concrete"
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/abstract-template-prompt-hoists-payloadref/input/meta.ai.json

@@ -0,0 +1,31 @@
+{
+  "metadata.root": {
+    "package": "acme::ai",
+    "children": [
+      {
+        "object.value": {
+          "name": "AuthorBrief",
+          "children": [
+            { "field.string": { "name": "displayName" } }
+          ]
+        }
+      },
+      {
+        "template.prompt": {
+          "name": "BasePrompt",
+          "abstract": true,
+          "@textRef": "prompt/base",
+          "@format": "xml"
+        }
+      },
+      {
+        "template.prompt": {
+          "name": "ConcretePrompt",
+          "extends": "acme::ai::BasePrompt",
+          "@payloadRef": "acme::ai::AuthorBrief",
+          "@textRef": "prompt/concrete"
+        }
+      }
+    ]
+  }
+}

server/csharp/MetaObjects/Loader/ValidationPasses.cs

@@ -1760,15 +1760,21 @@ private static void ValidateAttrSchemaNode(
         // --- Check 1: required attrs present ---
         // Use Attrs() (effective = own + inherited) so a node that legitimately
         // inherits a required attr from its super is not flagged as missing it.
-        var effective = node.Attrs();
-        foreach (var spec in byName.Values)
+        // #236: an ABSTRACT node is a template, not instantiated — it may omit a required
+        // attr for concrete subtypes / `extends` to supply. Enforcement stays at the
+        // concrete level (a concrete's resolving Attrs() must satisfy it). ADR-0039.
+        if (!node.IsAbstract)
         {
-            if (spec.Required && !effective.ContainsKey(spec.Name))
+            var effective = node.Attrs();
+            foreach (var spec in byName.Values)
             {
-                errors.Add(new MetaError(
-                    $"{NodeLabel(node)} is missing required attribute '@{spec.Name}'",
-                    ErrorCode.ERR_MISSING_REQUIRED_ATTR,
-                    Envelope: node.Source));
+                if (spec.Required && !effective.ContainsKey(spec.Name))
+                {
+                    errors.Add(new MetaError(
+                        $"{NodeLabel(node)} is missing required attribute '@{spec.Name}'",
+                        ErrorCode.ERR_MISSING_REQUIRED_ATTR,
+                        Envelope: node.Source));
+                }
             }
         }
 

server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java

@@ -352,6 +352,11 @@ private static void validateRequiredAttrsNode(MetaData node, MetaDataRegistry re
         TypeDefinition def = registry.getTypeDefinition(type, subType);
         if (def == null) return; // unregistered (test scaffold etc.) — skip silently
 
+        // #236: an ABSTRACT node is a template, not instantiated — it may omit a required
+        // attr for concrete subtypes / extends: to supply. Enforcement stays at the
+        // concrete level (a concrete's effective attrs must satisfy it). ADR-0039.
+        if (isAbstract(node)) return;
+
         // Collect required ATTR requirements: direct first (wins on name
         // collision), then inherited for names not directly declared.
         Map<String, ChildRequirement> requiredAttrs = new java.util.LinkedHashMap<>();

server/python/src/metaobjects/loader/validation_passes.py

@@ -437,18 +437,22 @@ def _validate_attr_schema(
 
         # --- Check 1: required attrs must be present (uses node.attrs() = effective,
         #     so an inherited attr from the super chain satisfies the requirement) ---
-        present_attrs = node.attrs()
-        for schema in schemas:
-            if not schema.required:
-                continue
-            if schema.name not in present_attrs:
-                errors.append(
-                    MetaError(
-                        f"{_node_label(node)} is missing required attribute '@{schema.name}'",
-                        ErrorCode.ERR_MISSING_REQUIRED_ATTR,
-                        envelope=node.source,
+        # #236: an ABSTRACT node is a template, not instantiated — it may omit a required
+        # attr for concrete subtypes / `extends` to supply. Enforcement stays at the
+        # concrete level (a concrete's resolving attrs() must satisfy it). ADR-0039.
+        if not node.is_abstract:
+            present_attrs = node.attrs()
+            for schema in schemas:
+                if not schema.required:
+                    continue
+                if schema.name not in present_attrs:
+                    errors.append(
+                        MetaError(
+                            f"{_node_label(node)} is missing required attribute '@{schema.name}'",
+                            ErrorCode.ERR_MISSING_REQUIRED_ATTR,
+                            envelope=node.source,
+                        )
                     )
-                )
 
         # --- Checks 2 + 3: own attrs only (inherited attrs were already checked on
         #     the node that declared them; re-checking would double-report) ---

server/typescript/packages/metadata/src/attr-schema-validate.ts

@@ -225,15 +225,25 @@ function validateNode(
   // Contrast with Checks 2+3 below, which iterate own attrs only: inherited attrs
   // were already validated on the node that declared them, so re-checking would
   // double-report. This mirrors the effective-vs-own split in subtype-rules.ts.
-  const effective = node.attrs();
-  for (const spec of byName.values()) {
-    if (spec.required && !effective.has(spec.name)) {
-      errors.push(
-        new ParseError(
-          `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
-          { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source },
-        ),
-      );
+  //
+  // #236: an ABSTRACT node is a template, not an instantiated node — it may omit a
+  // required attr for concrete subtypes / `extends` to supply (e.g. an abstract
+  // `template.prompt` that hoists shared children but leaves `@payloadRef` to its
+  // concretes). Enforcement stays at the CONCRETE level: a concrete node's resolving
+  // attrs() must satisfy the requirement (a concrete missing it — inherited or own —
+  // still errors). Consistent with ADR-0039 (resolving-default; abstract = the
+  // metamodel's incompleteness escape).
+  if (!node.isAbstract) {
+    const effective = node.attrs();
+    for (const spec of byName.values()) {
+      if (spec.required && !effective.has(spec.name)) {
+        errors.push(
+          new ParseError(
+            `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
+            { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source },
+          ),
+        );
+      }
     }
   }
 

server/typescript/packages/metadata/test/template-validation.test.ts

@@ -120,3 +120,38 @@ describe("template load-time validation", () => {
     expect(errs.length).toBeGreaterThan(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// #236 — an ABSTRACT template.prompt may omit the required @payloadRef (concrete
+// subtypes / extends supply it). The required-attr check reads the RESOLVING set
+// (a concrete inheriting via extends is satisfied) and EXEMPTS abstract nodes (a
+// template is not instantiated; its incompleteness is fine). Consistent with ADR-0039.
+// ---------------------------------------------------------------------------
+describe("#236 abstract template.prompt may omit required @payloadRef", () => {
+  test("abstract WITHOUT @payloadRef + concrete extends supplying it → loads", async () => {
+    const errs = await load([
+      authorBrief,
+      { "template.prompt": { name: "BasePrompt", abstract: true, "@textRef": "p/base" } },
+      { "template.prompt": { name: "Concrete", extends: "test::BasePrompt", "@payloadRef": "AuthorBrief", "@textRef": "p/c" } },
+    ]);
+    expect(errs).toEqual([]);
+  });
+
+  test("concrete INHERITS @payloadRef from an abstract via extends → loads (resolving)", async () => {
+    const errs = await load([
+      authorBrief,
+      { "template.prompt": { name: "BasePrompt", abstract: true, "@payloadRef": "AuthorBrief", "@textRef": "p/base" } },
+      { "template.prompt": { name: "Concrete", extends: "test::BasePrompt", "@textRef": "p/c" } },
+    ]);
+    expect(errs).toEqual([]);
+  });
+
+  test("CONCRETE missing @payloadRef (nowhere in its chain) → ERR_MISSING_REQUIRED_ATTR", async () => {
+    const errs = await load([
+      authorBrief,
+      { "template.prompt": { name: "BasePrompt", abstract: true, "@textRef": "p/base" } },
+      { "template.prompt": { name: "Concrete", extends: "test::BasePrompt", "@textRef": "p/c" } },
+    ]);
+    expect(errs.map((e) => e.code)).toContain("ERR_MISSING_REQUIRED_ATTR");
+  });
+});