fix: address code review issues from issue #19 implementation

- Wire inferPropertyKind into newUnknownObject via FieldKinds field on
  UnknownElement — eliminates dead code, surfaces property kind hints
- inferPropertyKind: implement key-based shortcuts ($ID/$ContainerID → "id",
  $Type → "type-discriminator"); use extractBsonArrayWithMarker to classify
  array fields as collection:by-name/part-secondary/part-primary
- extractBsonArrayWithMarker: handle marker=1 (by-name arrays) alongside 2/3
- UnknownElement: add FieldKinds map[string]string field for diagnostic output
- writer_microflow.go: add *model.UnknownElement case in serializeMicroflowObject
  to write RawFields back as-is, completing P0 round-trip fidelity
- parseMicroflowObject: return nil for empty $Type (symmetric with workflow parser)
- Fix init() comment: clarify actual reason (initialization order) vs incorrect
  "recursion" claim

Author: engalar

model/types.go

@@ -718,12 +718,18 @@ type DistributionSettings struct {
 // UnknownElement is a generic fallback for BSON elements with unrecognized $Type values.
 // It preserves all raw BSON fields so developers can diagnose unimplemented types
 // without silent data loss.
+//
+// FieldKinds maps each raw field name to its inferred Mendix property kind
+// (e.g. "primitive", "part", "by-name-reference", "collection:part-primary").
+// This guides implementors in writing a proper parser without inspecting the
+// mendixmodelsdk JS source manually.
 type UnknownElement struct {
 	BaseElement
-	Position  Point          `json:"position,omitempty"`
-	Name      string         `json:"name,omitempty"`
-	Caption   string         `json:"caption,omitempty"`
-	RawFields map[string]any `json:"-"`
+	Position   Point             `json:"position,omitempty"`
+	Name       string            `json:"name,omitempty"`
+	Caption    string            `json:"caption,omitempty"`
+	RawFields  map[string]any    `json:"-"`
+	FieldKinds map[string]string `json:"-"`
 }
 
 // GetPosition returns the element's position (satisfies microflows.MicroflowObject).

sdk/mpr/parser.go

@@ -174,21 +174,31 @@ func extractBsonArrayWithMarker(v any) BsonArrayInfo {
 	}
 
 	if len(slice) > 0 {
-		if marker, ok := slice[0].(int32); ok && (marker == 2 || marker == 3) {
+		if marker, ok := slice[0].(int32); ok && (marker == 1 || marker == 2 || marker == 3) {
 			return BsonArrayInfo{Marker: marker, Items: slice[1:]}
 		}
 	}
 	return BsonArrayInfo{Items: slice}
 }
 
-// inferPropertyKind determines whether a BSON field value represents a primitive,
-// a by-name reference, or a part (embedded object). This is used by the generic
-// unknown-element parser to preserve raw fields with semantic context.
+// inferPropertyKind determines the Mendix property kind of a BSON field from its key
+// and value shape. Returns one of: "id", "type-discriminator", "by-name-reference",
+// "primitive", "part", "collection:by-name" (marker=1), "collection:part-secondary"
+// (marker=2), "collection:part-primary" (marker=3), "collection".
+// Used by UnknownElement to surface diagnostic info when an unimplemented $Type is encountered.
 func inferPropertyKind(key string, v any) string {
 	if v == nil {
 		return "primitive"
 	}
 
+	// Key-based shortcuts take priority over value shape.
+	switch key {
+	case "$ID", "$ContainerID":
+		return "id"
+	case "$Type":
+		return "type-discriminator"
+	}
+
 	switch val := v.(type) {
 	case map[string]any:
 		if _, hasType := val["$Type"]; hasType {
@@ -219,10 +229,19 @@ func inferPropertyKind(key string, v any) string {
 		return "primitive"
 
 	case primitive.A, []any:
+		info := extractBsonArrayWithMarker(v)
+		switch info.Marker {
+		case 1:
+			return "collection:by-name"
+		case 2:
+			return "collection:part-secondary"
+		case 3:
+			return "collection:part-primary"
+		}
 		return "collection"
 
 	case string:
-		// Heuristic: qualified names like "Module.Entity" are likely by-name references
+		// Heuristic: qualified names like "Module.Entity" are likely by-name references.
 		if strings.Contains(val, ".") && !strings.Contains(val, " ") && !strings.Contains(val, "/") {
 			return "by-name-reference"
 		}

sdk/mpr/parser_microflow.go

@@ -247,7 +247,9 @@ func parseMicroflowObjectCollection(raw map[string]any) *microflows.MicroflowObj
 
 // microflowObjectParsers maps Mendix $Type strings to their parser functions.
 // Adding support for a new type requires only one new entry here.
-// Initialized in init() to avoid initialization cycle (parseLoopedActivity → parseMicroflowObjectCollection → parseMicroflowObject).
+// Declared as a nil var and populated in init() so that the map literal can
+// reference parseLoopedActivity, which itself calls parseMicroflowObjectCollection,
+// keeping the package-level initialization order unambiguous.
 var microflowObjectParsers map[string]func(map[string]any) microflows.MicroflowObject
 
 func init() {
@@ -267,8 +269,12 @@ func init() {
 }
 
 // parseMicroflowObject parses a single microflow object based on its $Type.
+// Returns nil for elements with an empty $Type (corrupt or placeholder records).
 func parseMicroflowObject(raw map[string]any) microflows.MicroflowObject {
 	typeName, _ := raw["$Type"].(string)
+	if typeName == "" {
+		return nil
+	}
 	if fn, ok := microflowObjectParsers[typeName]; ok {
 		return fn(raw)
 	}

sdk/mpr/parser_unknown.go

@@ -6,6 +6,8 @@ import "github.com/mendixlabs/mxcli/model"
 
 // newUnknownObject creates an UnknownElement that preserves raw BSON fields
 // for unrecognized $Type values, preventing silent data loss.
+// FieldKinds is populated by inferPropertyKind so callers can see the inferred
+// Mendix property kind for each field without inspecting the SDK JS source.
 func newUnknownObject(typeName string, raw map[string]any) *model.UnknownElement {
 	id := ""
 	if raw != nil {
@@ -19,6 +21,10 @@ func newUnknownObject(typeName string, raw map[string]any) *model.UnknownElement
 		elem.Position = parsePoint(raw["RelativeMiddlePoint"])
 		elem.Name = extractString(raw["Name"])
 		elem.Caption = extractString(raw["Caption"])
+		elem.FieldKinds = make(map[string]string, len(raw))
+		for k, v := range raw {
+			elem.FieldKinds[k] = inferPropertyKind(k, v)
+		}
 	}
 	return elem
 }

sdk/mpr/writer_microflow.go

@@ -502,6 +502,18 @@ func serializeMicroflowObject(obj microflows.MicroflowObject) bson.D {
 			{Key: "Size", Value: sizeToString(o.Size)},
 		}
 
+	case *model.UnknownElement:
+		// Write-through: serialize RawFields back as-is so unknown activities
+		// are not silently dropped when the MPR is saved.
+		if o.RawFields == nil {
+			return nil
+		}
+		doc := make(bson.D, 0, len(o.RawFields))
+		for k, v := range o.RawFields {
+			doc = append(doc, bson.E{Key: k, Value: v})
+		}
+		return doc
+
 	default:
 		return nil
 	}