feat(fr-033): Java port S-B1 — embed spec/metamodel JSON + reader + descriptions

Bundles the 15 shared spec/metamodel/*.json into the metadata module (byte-gated)
and adds a reader that sources every type/attr/common-attr description (+ rules/
example/whenToUse) from them onto the Java registry — single-sourced, byte-identical
to TS, never hand-copied. The manifest's description fields now match the golden;
RegistryManifestConformanceTest stays RED pending the strict children graph +
cardinality + per-subtype attr scoping reconciliation (sub-step B2).

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

Author: dmealing

server/java/metadata/pom.xml

@@ -28,6 +28,38 @@
                     </execution>
                 </executions>
             </plugin>
+            <!-- FR-033: bundle the repo-root spec/metamodel/*.json (the 15 shared
+                 provider-definition files; byte-identical cross-port by design) into
+                 the metadata jar at spec/metamodel/, so the SpecMetamodelReader can
+                 read them off the classpath at registration time (AOT-safe, ADR-0001
+                 — embed, never runtime-scan an arbitrary filesystem path). The
+                 byte-identity gate (SpecMetamodelEmbedTest) asserts the embedded copy
+                 equals the repo-root source. -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-resources-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>bundle-spec-metamodel</id>
+                        <phase>generate-resources</phase>
+                        <goals>
+                            <goal>copy-resources</goal>
+                        </goals>
+                        <configuration>
+                            <outputDirectory>${project.build.outputDirectory}/spec/metamodel</outputDirectory>
+                            <resources>
+                                <resource>
+                                    <directory>${maven.multiModuleProjectDirectory}/../../spec/metamodel</directory>
+                                    <includes>
+                                        <include>*.json</include>
+                                    </includes>
+                                    <filtering>false</filtering>
+                                </resource>
+                            </resources>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
     </build>
 

server/java/metadata/src/main/java/com/metaobjects/registry/ChildRequirement.java

@@ -320,6 +320,23 @@ public String getDocDescription() {
         return docDescription;
     }
 
+    /**
+     * FR-033 — a copy of this requirement carrying the given doc description, with
+     * all other facets (name/type/subType/required + the constraint matchers /
+     * constraintId / validationDescription) preserved. Used by
+     * {@link MetaDataRegistry#applySpecDescriptions} to thread the
+     * {@code spec/metamodel/*.json} attr description onto an already-registered
+     * requirement without disturbing its placement/validation behavior.
+     *
+     * @param docDescription the FR-033 doc description to carry
+     * @return a new ChildRequirement identical apart from the doc description
+     */
+    public ChildRequirement withDocDescription(String docDescription) {
+        return new ChildRequirement(name, expectedType, expectedSubType, required,
+                parentMatcher, childMatcher, valueValidator, constraintId, validationDescription,
+                docDescription);
+    }
+
     @Override
     public boolean equals(Object obj) {
         if (this == obj) return true;

server/java/metadata/src/main/java/com/metaobjects/registry/CommonAttributeDef.java

@@ -20,11 +20,25 @@
  * (every type / every subType). Used by the cross-language commonAttrs
  * contract (documentation provider in TS / C# / Python / Java).
  *
- * @param name      bare attribute name (no {@code @} prefix; e.g. {@code "description"})
- * @param valueType attribute value subtype (e.g. {@code StringAttribute.SUBTYPE_STRING},
- *                  {@code BooleanAttribute.SUBTYPE_BOOLEAN})
- * @param isArray   {@code true} if the attribute holds an array of {@code valueType}
- *                  (e.g. {@code aliases}, {@code seeAlso}, {@code replacedBy})
+ * @param name        bare attribute name (no {@code @} prefix; e.g. {@code "description"})
+ * @param valueType   attribute value subtype (e.g. {@code StringAttribute.SUBTYPE_STRING},
+ *                    {@code BooleanAttribute.SUBTYPE_BOOLEAN})
+ * @param isArray     {@code true} if the attribute holds an array of {@code valueType}
+ *                    (e.g. {@code aliases}, {@code seeAlso}, {@code replacedBy})
+ * @param description FR-033 — the human/AI-facing documentation prose, sourced from the
+ *                    universal {@code *.*} entry of the embedded {@code spec/metamodel/
+ *                    documentation.json}. {@code ""} when not sourced (back-compat). The
+ *                    registry-conformance manifest emits this on each common attr.
  */
-public record CommonAttributeDef(String name, String valueType, boolean isArray) {
+public record CommonAttributeDef(String name, String valueType, boolean isArray, String description) {
+
+    /** Back-compat constructor — no description (empty string). */
+    public CommonAttributeDef(String name, String valueType, boolean isArray) {
+        this(name, valueType, isArray, "");
+    }
+
+    /** A copy of this def carrying the given FR-033 description. */
+    public CommonAttributeDef withDescription(String description) {
+        return new CommonAttributeDef(name, valueType, isArray, description != null ? description : "");
+    }
 }

server/java/metadata/src/main/java/com/metaobjects/registry/MetaDataRegistry.java

@@ -712,6 +712,134 @@ public Collection<CommonAttributeDef> getCommonAttributes() {
         return List.copyOf(commonAttributes.values());
     }
 
+    /**
+     * FR-033 (sub-step B1) — source every type / attr / common-attr <em>description</em>
+     * (+ optional {@code rules}/{@code example}/{@code whenToUse}) from the shared
+     * {@code spec/metamodel/*.json} (the cross-port single source of truth, read by
+     * {@link com.metaobjects.registry.spec.SpecMetamodelReader}) onto this registry.
+     *
+     * <p>Applied DURING composition, BEFORE {@link #seal()} (the type definitions are
+     * immutable, so each {@link TypeDefinition} carrying a JSON description is rebuilt
+     * and re-put; each attr {@link ChildRequirement} that the JSON describes is copied
+     * with its {@code docDescription}; each {@link CommonAttributeDef} is replaced by a
+     * copy carrying the universal {@code *.*} description). Descriptions come from the
+     * JSON ONLY — never hand-copied — so they are byte-identical to the TS reference.</p>
+     *
+     * <p>Where Java registers an attr the JSON does NOT describe for that subtype (or
+     * vice-versa) this is left untouched — that scoping mismatch is reconciled in
+     * sub-step B2; B1 applies descriptions only where they match.</p>
+     *
+     * @param reader the parsed embedded spec/metamodel reader
+     */
+    public synchronized void applySpecDescriptions(com.metaobjects.registry.spec.SpecMetamodelReader reader) {
+        Objects.requireNonNull(reader, "reader must not be null");
+        checkNotSealed("applySpecDescriptions");
+
+        // Pass 1 — rebuild every TypeDefinition with the JSON type docs + per-attr
+        // doc descriptions on its DIRECT (+ wildcard) child requirements.
+        for (Map.Entry<MetaDataTypeId, TypeDefinition> entry : new ArrayList<>(typeDefinitions.entrySet())) {
+            MetaDataTypeId id = entry.getKey();
+            TypeDefinition def = entry.getValue();
+
+            com.metaobjects.registry.spec.SpecMetamodelReader.DocFacet typeDoc =
+                    reader.typeDoc(id.type(), id.subType());
+            String description = (typeDoc != null && typeDoc.description() != null)
+                    ? typeDoc.description() : def.getDescription();
+            String rules = typeDoc != null ? typeDoc.rules() : def.getRules();
+            String example = typeDoc != null ? typeDoc.example() : def.getExample();
+            String whenToUse = typeDoc != null ? typeDoc.whenToUse() : def.getWhenToUse();
+
+            // Rebuild the DIRECT child requirements, threading attr doc descriptions.
+            Map<String, ChildRequirement> directReqs = new LinkedHashMap<>();
+            for (ChildRequirement req : def.getDirectChildRequirements()) {
+                ChildRequirement rebuilt = req;
+                if (MetaAttribute.TYPE_ATTR.equals(req.getExpectedType())
+                        && req.getName() != null && !"*".equals(req.getName())) {
+                    com.metaobjects.registry.spec.SpecMetamodelReader.AttrEntry attrDoc =
+                            reader.attrDoc(id.type(), id.subType(), req.getName());
+                    if (attrDoc != null && attrDoc.description() != null) {
+                        rebuilt = req.withDocDescription(attrDoc.description());
+                    }
+                }
+                String key = rebuilt.getName();
+                if (key == null || "*".equals(key)) {
+                    key = "*:" + rebuilt.getExpectedType() + ":" + rebuilt.getExpectedSubType();
+                }
+                directReqs.put(key, rebuilt);
+            }
+
+            TypeDefinition rebuiltDef = new TypeDefinition(
+                    def.getImplementationClass(), id.type(), id.subType(), description,
+                    directReqs, def.getParentType(), def.getParentSubType(),
+                    rules, example, whenToUse, def.getParents());
+            typeDefinitions.put(id, rebuiltDef);
+        }
+
+        // Pass 2 — re-resolve inheritance so each child re-inherits the REBUILT parent
+        // requirements (carrying descriptions). Crucially, an inherited attr req is
+        // re-described against the CHILD's own (type, subType): the JSON sometimes
+        // scopes an attr to a concrete subtype (e.g. @discriminator on object.entity)
+        // while Java declares it on the base (object.base) and inherits it. Describing
+        // the inherited copy by the child subtype lands the JSON description on the
+        // child where the cross-port golden carries it, and correctly leaves it empty
+        // on a sibling the JSON does NOT scope it to. Where Java's inheritance direction
+        // disagrees with the JSON scope, that is the B2 scoping reconciliation — B1 only
+        // applies the description where the JSON declares it for that subtype.
+        for (TypeDefinition def : new ArrayList<>(typeDefinitions.values())) {
+            if (def.hasParent()) {
+                TypeDefinition parent = typeDefinitions.get(
+                        new MetaDataTypeId(def.getParentType(), def.getParentSubType()));
+                if (parent != null) {
+                    resolveInheritanceForDefinition(def, parent);
+                    describeInheritedAttrs(def, reader);
+                }
+            }
+        }
+
+        // Pass 3 — common-attr descriptions from the universal *.* documentation entry.
+        for (Map.Entry<String, CommonAttributeDef> e : new ArrayList<>(commonAttributes.entrySet())) {
+            com.metaobjects.registry.spec.SpecMetamodelReader.AttrEntry doc =
+                    reader.commonAttrDoc(e.getKey());
+            if (doc != null && doc.description() != null) {
+                commonAttributes.put(e.getKey(), e.getValue().withDescription(doc.description()));
+            }
+        }
+    }
+
+    /**
+     * FR-033 (sub-step B1) — re-describe a definition's INHERITED attr requirements
+     * against the definition's OWN {@code (type, subType)}, so a JSON description that
+     * the spec scopes to a concrete subtype lands on the inherited copy where the
+     * cross-port golden carries it. Replaces each inherited attr requirement with a
+     * doc-described copy when the spec describes that attr for this subtype.
+     */
+    private void describeInheritedAttrs(TypeDefinition def,
+                                        com.metaobjects.registry.spec.SpecMetamodelReader reader) {
+        Map<String, ChildRequirement> inherited = def.getInheritedChildRequirements();
+        if (inherited.isEmpty()) {
+            return;
+        }
+        Map<String, ChildRequirement> redescribed = new LinkedHashMap<>(inherited);
+        boolean changed = false;
+        for (Map.Entry<String, ChildRequirement> e : inherited.entrySet()) {
+            ChildRequirement req = e.getValue();
+            if (!MetaAttribute.TYPE_ATTR.equals(req.getExpectedType())
+                    || req.getName() == null || "*".equals(req.getName())) {
+                continue;
+            }
+            com.metaobjects.registry.spec.SpecMetamodelReader.AttrEntry doc =
+                    reader.attrDoc(def.getType(), def.getSubType(), req.getName());
+            if (doc != null && doc.description() != null
+                    && !doc.description().equals(req.getDocDescription())) {
+                redescribed.put(e.getKey(), req.withDocDescription(doc.description()));
+                changed = true;
+            }
+        }
+        if (changed) {
+            def.populateInheritedRequirements(redescribed);
+        }
+    }
+
     /**
      * Lightweight array-shape predicate for common-array-attr validation. Mirrors
      * the per-type {@code AttributeConstraintBuilder.isArrayValue} contract:

server/java/metadata/src/main/java/com/metaobjects/registry/RegistryManifest.java

@@ -106,7 +106,20 @@ private RegistryManifest() {
      * @return a new registry composed from the metamodel provider set
      */
     public static MetaDataRegistry composeMetamodelRegistry() {
-        return MetaDataRegistry.compose(metamodelProviders());
+        MetaDataRegistry registry = MetaDataRegistry.compose(metamodelProviders());
+        // Force the lazy core-constraint init NOW: it expands the named inherited
+        // attr child-requirements (e.g. field.base's `required`/`default`/`unique`
+        // onto each concrete field subtype). Those named requirements must exist
+        // BEFORE applySpecDescriptions rebuilds the type definitions, otherwise the
+        // rebuild would not see them and their descriptions would never land.
+        registry.getAllValidationConstraints();
+        // FR-033 (sub-step B1): source every type / attr / common-attr description
+        // (+ rules/example/whenToUse) from the embedded spec/metamodel/*.json — the
+        // cross-port single source of truth — onto the freshly-composed registry,
+        // BEFORE any seal. Single-sourced, byte-identical to TS; never hand-copied.
+        registry.applySpecDescriptions(
+                com.metaobjects.registry.spec.SpecMetamodelReader.load());
+        return registry;
     }
 
     /**
@@ -572,12 +585,13 @@ public static String emit(MetaDataRegistry registry) {
         // commonAttrs: sorted by name. An array-shaped common attr is the scalar
         // value-type plus the orthogonal isArray flag (the retired stringarray
         // subtype) — matching the cross-port {valueType, isArray} contract. The
-        // FR-033 per-commonAttr description has no Java source yet (CommonAttributeDef
-        // carries none) → empty string; sub-step B sources it from the embedded JSON.
+        // FR-033 (sub-step B): the per-commonAttr description is now sourced from the
+        // universal *.* entry of the embedded spec/metamodel/documentation.json and
+        // applied onto each CommonAttributeDef at composition time (pre-seal).
         List<ManifestAttr> commonAttrs = new ArrayList<>();
         for (CommonAttributeDef def : registry.getCommonAttributes()) {
             commonAttrs.add(new ManifestAttr(def.name(), def.valueType(), def.isArray(), false,
-                "", null, null, null));
+                def.description() != null ? def.description() : "", null, null, null));
         }
         commonAttrs.sort(Comparator.comparing(ManifestAttr::name));