feat(validation): warn when an annotation type is not known

docs/explanation/tenant-types.md

@@ -71,6 +71,17 @@ own; the client only needs enough types to turn JSON into bytes and back.
 - A library that another library depends on, or whose types entity schemas
   use, cannot be deleted, even with `mode=FORCE`. The schemas show up as
   references to the library, so impact analysis lists them too.
+- An annotation in a `metadata` list, including the `metadata` of fields
+  nested in a built-in schema, is checked against the built-in types and the
+  live libraries in the entity's namespace, counting libraries written
+  earlier in the same batch. A type URL neither declares raises the
+  `UNKNOWN_ANNOTATION_TYPE` warning, with the annotation's path in
+  `subject_field`. The write still succeeds, so annotations keep working
+  while their library is drafted. Built-in annotations match by their full
+  message name under any host, so a look-alike such as
+  `acme.v1.MyOrphanAnnotation` suppresses nothing, and a misspelled one says
+  so instead of failing silently. If the namespace's libraries fail to compile, the warning still names every
+  type URL that is not built in and says the libraries could not be checked.
 
 ## Breaking changes become new packages
 

rsworkspace/crates/trogon-atlas-server/src/analysis.rs

@@ -890,10 +890,10 @@ fn swimlane_state_endpoint(
 }
 
 pub(crate) fn is_derived_field(field: &pb::FieldSpec) -> bool {
-    field.metadata.iter().any(|m| {
-        m.type_url
-            .ends_with("trogonatlas.eventmodel.v1alpha1.DerivedFieldAnnotation")
-    })
+    field
+        .metadata
+        .iter()
+        .any(|m| crate::annotation_type::BuiltinAnnotation::DERIVED_FIELD.matches(m))
 }
 
 fn fields_of(entity: &pb::Entity) -> Vec<pb::FieldSpec> {

rsworkspace/crates/trogon-atlas-server/src/annotation_type.rs

@@ -0,0 +1,64 @@
+use trogon_atlas_types::TypeUrl;
+
+/// A built-in annotation message, recognized only by its exact protobuf
+/// full name so a look-alike type from another package never passes for it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct BuiltinAnnotation(&'static str);
+
+impl BuiltinAnnotation {
+    pub(crate) const ASSUMPTION: Self =
+        Self("trogonatlas.annotation.v1alpha1.AssumptionAnnotation");
+    pub(crate) const CODE_REF: Self = Self("trogonatlas.annotation.v1alpha1.CodeRefAnnotation");
+    pub(crate) const DERIVED_FIELD: Self =
+        Self("trogonatlas.eventmodel.v1alpha1.DerivedFieldAnnotation");
+    pub(crate) const LIFECYCLE: Self = Self("trogonatlas.annotation.v1alpha1.LifecycleAnnotation");
+    pub(crate) const MIXED_SURFACE: Self =
+        Self("trogonatlas.eventmodel.v1alpha1.MixedSurfaceAnnotation");
+    pub(crate) const OPEN_QUESTION: Self =
+        Self("trogonatlas.annotation.v1alpha1.OpenQuestionAnnotation");
+    pub(crate) const ORPHAN: Self = Self("trogonatlas.eventmodel.v1alpha1.OrphanAnnotation");
+    pub(crate) const PERSONAL_DATA: Self =
+        Self("trogonatlas.eventmodel.v1alpha1.PersonalDataAnnotation");
+    pub(crate) const PINNED_REF: Self = Self("trogonatlas.eventmodel.v1alpha1.PinnedRefAnnotation");
+    pub(crate) const SHARED_CONSUMERS: Self =
+        Self("trogonatlas.eventmodel.v1alpha1.SharedConsumersAnnotation");
+    pub(crate) const UUIDV5_IDENTITY: Self =
+        Self("trogonatlas.eventmodel.v1alpha1.Uuidv5IdentityAnnotation");
+
+    pub(crate) fn matches(self, any: &prost_types::Any) -> bool {
+        TypeUrl::parse(&any.type_url).is_ok_and(|url| url.full_name() == self.0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn any(type_url: &str) -> prost_types::Any {
+        prost_types::Any {
+            type_url: type_url.into(),
+            value: Vec::new(),
+        }
+    }
+
+    #[test]
+    fn matches_the_exact_message_under_any_host() {
+        for url in [
+            "type.googleapis.com/trogonatlas.eventmodel.v1alpha1.OrphanAnnotation",
+            "example.com/types/trogonatlas.eventmodel.v1alpha1.OrphanAnnotation",
+        ] {
+            assert!(BuiltinAnnotation::ORPHAN.matches(&any(url)), "{url}");
+        }
+    }
+
+    #[test]
+    fn rejects_names_that_only_share_a_suffix() {
+        for url in [
+            "type.googleapis.com/acme.trogonatlas.eventmodel.v1alpha1.OrphanAnnotation",
+            "type.googleapis.com/acmetrogonatlas.eventmodel.v1alpha1.OrphanAnnotation",
+            "trogonatlas.eventmodel.v1alpha1.OrphanAnnotation",
+        ] {
+            assert!(!BuiltinAnnotation::ORPHAN.matches(&any(url)), "{url}");
+        }
+    }
+}

rsworkspace/crates/trogon-atlas-server/src/lib.rs

@@ -1,4 +1,5 @@
 pub mod analysis;
+mod annotation_type;
 pub mod artifacts;
 pub mod as_of;
 pub mod assessment;

rsworkspace/crates/trogon-atlas-server/src/service.rs

@@ -655,10 +655,7 @@ impl Drop for StreamChangesGuard {
 fn entity_lifecycle_status(entity: &pb::Entity) -> Option<String> {
     let metadata = crate::validation::entity_metadata(entity);
     for any in metadata {
-        if !any
-            .type_url
-            .ends_with("trogonatlas.annotation.v1alpha1.LifecycleAnnotation")
-        {
+        if !crate::annotation_type::BuiltinAnnotation::LIFECYCLE.matches(any) {
             continue;
         }
         if let Ok(ann) = <pb::LifecycleAnnotation as prost::Message>::decode(any.value.as_slice()) {
@@ -7395,6 +7392,16 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
             .type_libraries
             .check_schema(&*self.store, &entity, &[], branch.as_deref())
             .await?;
+        let annotation_issues = validation::unknown_annotation_type_issues(
+            &pb::EntityRef {
+                kind: kind as i32,
+                id: Some(id.clone()),
+            },
+            &self
+                .type_libraries
+                .unknown_annotation_types(&*self.store, &entity, &[], branch.as_deref())
+                .await?,
+        );
 
         let ran_scenarios = runs_scenarios(kind);
         let ran_strategic = is_strategic_kind(kind);
@@ -7416,6 +7423,7 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
                 &scenario_issues,
             )));
         }
+        scenario_issues.extend(annotation_issues);
         // Strategic findings never block: sequential puts of one problem
         // space are order dependent, so a context put before its subdomains
         // is transiently dangling and rejecting it would make the model
@@ -8436,18 +8444,38 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
                 _ => None,
             })
             .collect();
-        for m in metas.iter().filter(|m| m.is_put) {
-            if let Some(entity) = m.entity.as_ref() {
-                if let Some(admission) = self
-                    .type_libraries
-                    .check_schema(&*self.store, entity, &pending_libraries, branch.as_deref())
-                    .await?
-                {
-                    if !type_library_admissions.contains(&admission) {
-                        type_library_admissions.push(admission);
-                    }
+        let mut annotation_issues: Vec<Vec<pb::ValidationIssue>> =
+            std::iter::repeat_with(Vec::new).take(metas.len()).collect();
+        let removed_libraries: Vec<pb::Id> = metas
+            .iter()
+            .filter(|m| !m.is_put && m.kind == pb::EntityKind::TypeLibrary)
+            .map(|m| m.id.clone())
+            .collect();
+        let mut annotation_types = self.type_libraries.annotation_lookup(
+            &pending_libraries,
+            &removed_libraries,
+            branch.as_deref(),
+        );
+        for (m, issues) in metas.iter().zip(&mut annotation_issues) {
+            let Some(entity) = m.entity.as_ref().filter(|_| m.is_put) else {
+                continue;
+            };
+            if let Some(admission) = self
+                .type_libraries
+                .check_schema(&*self.store, entity, &pending_libraries, branch.as_deref())
+                .await?
+            {
+                if !type_library_admissions.contains(&admission) {
+                    type_library_admissions.push(admission);
                 }
             }
+            *issues = validation::unknown_annotation_type_issues(
+                &pb::EntityRef {
+                    kind: m.kind as i32,
+                    id: Some(m.id.clone()),
+                },
+                &annotation_types.unknown(&*self.store, entity).await?,
+            );
         }
 
         let invariant_changes: Vec<invariant_admission::Change> = metas
@@ -8607,8 +8635,7 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
         // replacement semantics, so the order of ops inside a batch never
         // matters. Each finding rides the op whose entity it is about, or
         // the op that caused it when that entity is not in the batch.
-        let mut per_op_validation: Vec<Vec<pb::ValidationIssue>> =
-            std::iter::repeat_with(Vec::new).take(metas.len()).collect();
+        let mut per_op_validation = annotation_issues;
         let has_strategic_ops = has_strategic_puts || has_strategic_deletes;
         let architecture_subjects = metas
             .iter()
@@ -8651,7 +8678,7 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
                         &changes, &base, &world,
                     ))
             {
-                per_op_validation[*op_index] = issues;
+                per_op_validation[*op_index].extend(issues);
             }
             let delete_ops: Vec<usize> = metas
                 .iter()
@@ -8674,7 +8701,7 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
                             &deletions, &before, &world, &reported,
                         ))
                 {
-                    per_op_validation[*op_index] = issues;
+                    per_op_validation[*op_index].extend(issues);
                 }
             }
         }
@@ -8710,7 +8737,7 @@ impl pb::event_model_service_server::EventModelService for EventModelServiceImpl
                     .into_iter()
                     .partition(|iss| iss.severity == pb::validation_issue::Severity::Error as i32);
                 if errors.is_empty() {
-                    per_op_validation[i] = non_errors;
+                    per_op_validation[i].extend(non_errors);
                 } else {
                     if first_error_index.is_none() {
                         first_error_index = Some(i);