fix(metadata): complete the cross-port @summary doc-attr rollout (Java + Python)

A parallel session added the `summary` documentation common attr to TS + C# + the
cross-port canonical (fixtures/registry-conformance/expected-registry.json) but NOT
to Java/Python/Kotlin. Because the registry manifest must be byte-identical across
all five ports, Java/Python/Kotlin registry-conformance diverged from the
summary-bearing canonical — leaving CI red on main for 6+ commits (the same
bun-test-doesn't-typecheck / red-but-merged pattern).

This completes the rollout so all five ports agree:
- Java: register `summary` in DocumentationConstants + DocumentationSchema
  (string, optional, position 1 after description). Covers Kotlin via the shared
  JVM metadata. Updated DocumentationConstantsTest to 8 attrs.
- Python: register it in doc_constants + doc_schema (same position). Updated
  test_common_attrs to 8 attrs.
- TS + C# already had it (from the parallel work); the merged canonical already
  carries `summary` + this branch's `provided` graduation.

Registry-conformance now green in ALL FIVE ports against the merged canonical:
TS 6, Java 3, Kotlin 1, C# 3, Python (812 suite). Metamodel conformance corpora
green (TS 326, Java 326, C# 596, Python). FR-019 (this branch) and FR-021 (main)
coexist; full workspace typecheck exit 0.

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

Author: dmealing

server/java/metadata/src/main/java/com/metaobjects/documentation/DocumentationConstants.java

@@ -26,16 +26,18 @@ public final class DocumentationConstants {
     private DocumentationConstants() {}
 
     public static final String DOC_ATTR_DESCRIPTION = "description";
+    public static final String DOC_ATTR_SUMMARY      = "summary";
     public static final String DOC_ATTR_TITLE        = "title";
     public static final String DOC_ATTR_NOTES        = "notes";
     public static final String DOC_ATTR_DEPRECATED   = "deprecated";
     public static final String DOC_ATTR_REPLACED_BY  = "replacedBy";
     public static final String DOC_ATTR_SEE_ALSO     = "seeAlso";
     public static final String DOC_ATTR_ALIASES      = "aliases";
 
-    /** All 7 names in declaration order. */
+    /** All 8 names in declaration order. */
     public static final List<String> DOC_ATTR_NAMES = List.of(
         DOC_ATTR_DESCRIPTION,
+        DOC_ATTR_SUMMARY,
         DOC_ATTR_TITLE,
         DOC_ATTR_NOTES,
         DOC_ATTR_DEPRECATED,

server/java/metadata/src/main/java/com/metaobjects/documentation/DocumentationSchema.java

@@ -51,7 +51,7 @@ public record CommonDocAttr(
         String description
     ) {}
 
-    /** The 7 universal documentation common attrs in declaration order. */
+    /** The 8 universal documentation common attrs in declaration order. */
     public static final List<CommonDocAttr> COMMON_DOC_ATTRS = List.of(
         new CommonDocAttr(
             DocumentationConstants.DOC_ATTR_DESCRIPTION,
@@ -60,6 +60,15 @@ public record CommonDocAttr(
             "Free-form user-facing prose. Markdown allowed, multi-line via YAML '|' block scalar. "
             + "Flows into doc-gen surfaces (JSDoc / XML-doc / Postgres COMMENT / Mermaid prose)."
         ),
+        new CommonDocAttr(
+            DocumentationConstants.DOC_ATTR_SUMMARY,
+            StringAttribute.SUBTYPE_STRING,
+            false,
+            "Short single-line tagline (OpenAPI `summary` pattern) — used in index tables, sidebar "
+            + "previews, and AI prompts where the full @description is too long. Optional supplement "
+            + "to @description; when @summary is unset, doc surfaces typically fall back to the first "
+            + "sentence of @description."
+        ),
         new CommonDocAttr(
             DocumentationConstants.DOC_ATTR_TITLE,
             StringAttribute.SUBTYPE_STRING,

server/java/metadata/src/test/java/com/metaobjects/documentation/DocumentationConstantsTest.java

@@ -12,7 +12,7 @@
 import static org.junit.Assert.assertTrue;
 
 /**
- * Cross-language vocabulary contract: the 7 doc attr names MUST be identical
+ * Cross-language vocabulary contract: the 8 doc attr names MUST be identical
  * across TS / C# / Java / Python. If you change a constant value here, the
  * cross-language conformance fixtures break.
  */
@@ -21,6 +21,7 @@ public class DocumentationConstantsTest {
     @Test
     public void constants_have_expected_cross_language_strings() {
         assertEquals("description", DocumentationConstants.DOC_ATTR_DESCRIPTION);
+        assertEquals("summary",     DocumentationConstants.DOC_ATTR_SUMMARY);
         assertEquals("title",       DocumentationConstants.DOC_ATTR_TITLE);
         assertEquals("notes",       DocumentationConstants.DOC_ATTR_NOTES);
         assertEquals("deprecated",  DocumentationConstants.DOC_ATTR_DEPRECATED);
@@ -30,20 +31,20 @@ public void constants_have_expected_cross_language_strings() {
     }
 
     @Test
-    public void DOC_ATTR_NAMES_contains_all_7_in_declaration_order() {
-        assertEquals(7, DocumentationConstants.DOC_ATTR_NAMES.size());
+    public void DOC_ATTR_NAMES_contains_all_8_in_declaration_order() {
+        assertEquals(8, DocumentationConstants.DOC_ATTR_NAMES.size());
         assertEquals(DocumentationConstants.DOC_ATTR_DESCRIPTION,
                      DocumentationConstants.DOC_ATTR_NAMES.get(0));
         assertEquals(DocumentationConstants.DOC_ATTR_ALIASES,
-                     DocumentationConstants.DOC_ATTR_NAMES.get(6));
+                     DocumentationConstants.DOC_ATTR_NAMES.get(7));
     }
 
     @Test
-    public void schema_has_7_entries_with_correct_value_types() {
-        assertEquals(7, DocumentationSchema.COMMON_DOC_ATTRS.size());
+    public void schema_has_8_entries_with_correct_value_types() {
+        assertEquals(8, DocumentationSchema.COMMON_DOC_ATTRS.size());
 
-        // First 5 are string, last 2 are stringarray — cross-language invariant
-        for (int i = 0; i < 5; i++) {
+        // First 6 are string, last 2 are stringarray — cross-language invariant
+        for (int i = 0; i < 6; i++) {
             assertEquals(
                 "attr[" + i + "] should be string",
                 StringAttribute.SUBTYPE_STRING,
@@ -52,24 +53,25 @@ public void schema_has_7_entries_with_correct_value_types() {
         }
         assertEquals(
             StringArrayAttribute.SUBTYPE_STRING_ARRAY,
-            DocumentationSchema.COMMON_DOC_ATTRS.get(5).valueType()
+            DocumentationSchema.COMMON_DOC_ATTRS.get(6).valueType()
         );
         assertEquals(
             StringArrayAttribute.SUBTYPE_STRING_ARRAY,
-            DocumentationSchema.COMMON_DOC_ATTRS.get(6).valueType()
+            DocumentationSchema.COMMON_DOC_ATTRS.get(7).valueType()
         );
     }
 
     @Test
     public void schema_attr_names_match_constants() {
         var attrs = DocumentationSchema.COMMON_DOC_ATTRS;
         assertEquals(DocumentationConstants.DOC_ATTR_DESCRIPTION, attrs.get(0).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_TITLE,       attrs.get(1).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_NOTES,       attrs.get(2).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_DEPRECATED,  attrs.get(3).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_REPLACED_BY, attrs.get(4).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_SEE_ALSO,    attrs.get(5).name());
-        assertEquals(DocumentationConstants.DOC_ATTR_ALIASES,     attrs.get(6).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_SUMMARY,     attrs.get(1).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_TITLE,       attrs.get(2).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_NOTES,       attrs.get(3).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_DEPRECATED,  attrs.get(4).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_REPLACED_BY, attrs.get(5).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_SEE_ALSO,    attrs.get(6).name());
+        assertEquals(DocumentationConstants.DOC_ATTR_ALIASES,     attrs.get(7).name());
     }
 
     @Test

server/python/src/metaobjects/documentation/doc_constants.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 DOC_ATTR_DESCRIPTION = "description"
+DOC_ATTR_SUMMARY     = "summary"
 DOC_ATTR_TITLE       = "title"
 DOC_ATTR_NOTES       = "notes"
 DOC_ATTR_DEPRECATED  = "deprecated"
@@ -11,6 +12,7 @@
 
 DOC_ATTR_NAMES: tuple[str, ...] = (
     DOC_ATTR_DESCRIPTION,
+    DOC_ATTR_SUMMARY,
     DOC_ATTR_TITLE,
     DOC_ATTR_NOTES,
     DOC_ATTR_DEPRECATED,

server/python/src/metaobjects/documentation/doc_schema.py

@@ -10,11 +10,13 @@
     DOC_ATTR_NOTES,
     DOC_ATTR_REPLACED_BY,
     DOC_ATTR_SEE_ALSO,
+    DOC_ATTR_SUMMARY,
     DOC_ATTR_TITLE,
 )
 
 common_doc_attrs: list[AttrSchema] = [
     AttrSchema(name=DOC_ATTR_DESCRIPTION,  value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_SUMMARY,      value_type=ATTR_SUBTYPE_STRING,      required=False),
     AttrSchema(name=DOC_ATTR_TITLE,        value_type=ATTR_SUBTYPE_STRING,      required=False),
     AttrSchema(name=DOC_ATTR_NOTES,        value_type=ATTR_SUBTYPE_STRING,      required=False),
     AttrSchema(name=DOC_ATTR_DEPRECATED,   value_type=ATTR_SUBTYPE_STRING,      required=False),

server/python/tests/unit/test_common_attrs.py

@@ -206,24 +206,25 @@ def test_conflict_reported_once_per_type_subtype() -> None:
 
 
 def test_doc_attr_names_tuple() -> None:
-    """DOC_ATTR_NAMES contains the 7 expected cross-language constant values."""
+    """DOC_ATTR_NAMES contains the 8 expected cross-language constant values."""
     assert DOC_ATTR_DESCRIPTION == "description"
     assert DOC_ATTR_TITLE       == "title"
     assert DOC_ATTR_NOTES       == "notes"
+    assert "summary"     in DOC_ATTR_NAMES
     assert "deprecated"  in DOC_ATTR_NAMES
     assert "replacedBy"  in DOC_ATTR_NAMES
     assert "seeAlso"     in DOC_ATTR_NAMES
     assert "aliases"     in DOC_ATTR_NAMES
-    assert len(DOC_ATTR_NAMES) == 7
+    assert len(DOC_ATTR_NAMES) == 8
 
 
 def test_common_doc_attrs_schema() -> None:
-    """common_doc_attrs has 7 entries; seeAlso and aliases are string arrays.
+    """common_doc_attrs has 8 entries; seeAlso and aliases are string arrays.
 
     Array attrs are now `string` + the orthogonal is_array flag (the retired
     `stringarray` subtype), matching Java's StringAttribute + @isArray.
     """
-    assert len(common_doc_attrs) == 7
+    assert len(common_doc_attrs) == 8
     by_name = {a.name: a for a in common_doc_attrs}
     assert by_name[DOC_ATTR_SEE_ALSO].value_type  == ATTR_SUBTYPE_STRING
     assert by_name[DOC_ATTR_SEE_ALSO].is_array is True