prep docs and service updates

src/Signals/StellaOps.Signals/Services/CallgraphIngestionService.cs

@@ -59,6 +59,10 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
         var artifactBytes = Convert.FromBase64String(request.ArtifactContentBase64);
         await using var parseStream = new MemoryStream(artifactBytes, writable: false);
         var parseResult = await parser.ParseAsync(parseStream, cancellationToken).ConfigureAwait(false);
+        var schemaVersion = !string.IsNullOrWhiteSpace(request.SchemaVersion)
+            ? request.SchemaVersion!
+            : parseResult.SchemaVersion;
+        var analyzerMeta = request.Analyzer ?? parseResult.Analyzer;
 
         parseStream.Position = 0;
         var artifactHash = ComputeSha256(artifactBytes);
@@ -71,8 +75,10 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
             Version = request.Version,
             ArtifactHash = artifactHash,
             GraphHash = graphHash,
+            SchemaVersion = schemaVersion,
             NodeCount = parseResult.Nodes.Count,
             EdgeCount = parseResult.Edges.Count,
+            RootCount = parseResult.Roots.Count,
             CreatedAt = timeProvider.GetUtcNow()
         };
 
@@ -95,14 +101,15 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
 
         var document = new CallgraphDocument
         {
-            Language = parser.Language,
-            Component = request.Component,
-            Version = request.Version,
-            Nodes = new List<CallgraphNode>(parseResult.Nodes),
-            Edges = new List<CallgraphEdge>(parseResult.Edges),
-            Metadata = request.Metadata is null
-                ? null
-                : new Dictionary<string, string?>(request.Metadata, StringComparer.OrdinalIgnoreCase),
+            Language = parser.Language,
+            Component = request.Component,
+            Version = request.Version,
+            Nodes = new List<CallgraphNode>(parseResult.Nodes),
+            Edges = new List<CallgraphEdge>(parseResult.Edges),
+            Roots = new List<CallgraphRoot>(parseResult.Roots),
+            Metadata = request.Metadata is null
+                ? null
+                : new Dictionary<string, string?>(request.Metadata, StringComparer.OrdinalIgnoreCase),
             Artifact = new CallgraphArtifactMetadata
             {
                 Path = artifactMetadata.Path,
@@ -119,7 +126,16 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
 
         document.Metadata ??= new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
         document.Metadata["formatVersion"] = parseResult.FormatVersion;
+        document.Metadata["schemaVersion"] = schemaVersion;
+        if (analyzerMeta is not null)
+        {
+            foreach (var kv in analyzerMeta)
+            {
+                document.Metadata[$"analyzer.{kv.Key}"] = kv.Value;
+            }
+        }
         document.GraphHash = graphHash;
+        document.SchemaVersion = schemaVersion;
 
         document = await repository.UpsertAsync(document, cancellationToken).ConfigureAwait(false);
 
@@ -138,7 +154,11 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
             document.Artifact.Hash,
             document.Artifact.CasUri,
             graphHash,
-            document.Artifact.ManifestCasUri);
+            document.Artifact.ManifestCasUri,
+            schemaVersion,
+            document.Nodes.Count,
+            document.Edges.Count,
+            document.Roots?.Count ?? 0);
     }
 
     private static void ValidateRequest(CallgraphIngestRequest request)
@@ -186,18 +206,73 @@ internal sealed class CallgraphIngestionService : ICallgraphIngestionService
     private static string ComputeGraphHash(CallgraphParseResult result)
     {
         var builder = new StringBuilder();
+
+        builder.Append("schema|").Append(result.SchemaVersion).AppendLine();
+
         foreach (var node in result.Nodes.OrderBy(n => n.Id, StringComparer.Ordinal))
         {
-            builder.Append(node.Id).Append('|').Append(node.Name).AppendLine();
+            builder
+                .Append(node.Id).Append('|')
+                .Append(node.Name).Append('|')
+                .Append(node.Kind).Append('|')
+                .Append(node.Namespace).Append('|')
+                .Append(node.File).Append('|')
+                .Append(node.Line?.ToString() ?? string.Empty).Append('|')
+                .Append(node.Purl).Append('|')
+                .Append(node.SymbolDigest).Append('|')
+                .Append(node.BuildId).Append('|')
+                .Append(node.CodeId).Append('|')
+                .Append(node.Language).Append('|')
+                .Append(Join(node.Evidence)).Append('|')
+                .Append(JoinDict(node.Analyzer))
+                .AppendLine();
         }
 
         foreach (var edge in result.Edges.OrderBy(e => e.SourceId, StringComparer.Ordinal).ThenBy(e => e.TargetId, StringComparer.Ordinal))
         {
-            builder.Append(edge.SourceId).Append("->").Append(edge.TargetId).AppendLine();
+            builder
+                .Append(edge.SourceId).Append("->").Append(edge.TargetId).Append('|')
+                .Append(edge.Type).Append('|')
+                .Append(edge.Purl).Append('|')
+                .Append(edge.SymbolDigest).Append('|')
+                .Append(edge.Confidence?.ToString() ?? string.Empty).Append('|')
+                .Append(Join(edge.Candidates)).Append('|')
+                .Append(Join(edge.Evidence))
+                .AppendLine();
+        }
+
+        foreach (var root in result.Roots.OrderBy(r => r.Id, StringComparer.Ordinal))
+        {
+            builder.Append("root|").Append(root.Id).Append('|').Append(root.Phase).Append('|').Append(root.Source).AppendLine();
         }
 
         return ComputeSha256(Encoding.UTF8.GetBytes(builder.ToString()));
     }
+
+    private static string Join(IEnumerable<string>? values)
+    {
+        if (values is null)
+        {
+            return string.Empty;
+        }
+
+        return string.Join(',', values.OrderBy(v => v, StringComparer.Ordinal));
+    }
+
+    private static string JoinDict(IReadOnlyDictionary<string, string?>? values)
+    {
+        if (values is null)
+        {
+            return string.Empty;
+        }
+
+        var ordered = new StringBuilder();
+        foreach (var kv in values.OrderBy(k => k.Key, StringComparer.Ordinal))
+        {
+            ordered.Append(kv.Key).Append('=').Append(kv.Value).Append(';');
+        }
+        return ordered.ToString();
+    }
 }
 
 /// <summary>