From 783aa735c477871eaf8fb051f990a8af253ccdc9 Mon Sep 17 00:00:00 2001
From: "flamingo[bot]" <277372822+flamingo[bot]@users.noreply.github.com>
Date: Mon, 7 Sep 2026 06:10:48 +0000
Subject: [PATCH] fix(OPENFRAM-010-6): TagAssignment.entityType/entityId
 relationship undocumented despite non-obvious polymorphic semantics

---
 .../openframe/data/document/tag/TagAssignment.java  | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/TagAssignment.java b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/TagAssignment.java
index 87004d1b4..c5fc63155 100644
--- a/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/TagAssignment.java
+++ b/openframe-data-mongo-common/src/main/java/com/openframe/data/document/tag/TagAssignment.java
@@ -22,8 +22,17 @@ public class TagAssignment implements TenantScoped {
     @Id
     private String id;
     private String tenantId;
+    /**
+     * Identifier of the tagged entity. The type of entity this id refers to
+     * (e.g., a device, a script, etc.) is determined by the sibling
+     * {@link #entityType} field.
+     */
     private String entityId;
     private String tagId;
+    /**
+     * Discriminator for {@link #entityId}, indicating which kind of entity
+     * (device, script, etc.) the id refers to.
+     */
     private TagEntityType entityType;
     /**
      * Per-device values for the tag key (e.g., ["site1", "site2"] for key "site").
@@ -31,5 +40,9 @@ public class TagAssignment implements TenantScoped {
      */
     private List<String> values;
     private Instant taggedAt;
+    /**
+     * Identifier of the user or system that created this tag assignment.
+     */
     private String taggedBy;
 }
+