git.stella-ops.org/src/Signals/StellaOps.Signals/Models/ProcSnapshotDocument.cs

using System.Text.Json.Serialization;

namespace StellaOps.Signals.Models;

/// <summary>
/// Document representing a proc snapshot for Java/.NET/PHP runtime parity.
/// Captures runtime-observed classpath, loaded assemblies, and autoload paths.
/// </summary>
public sealed class ProcSnapshotDocument
{
    /// <summary>
    /// Unique identifier for this snapshot (format: {tenant}/{image_digest}/{snapshot_hash}).
    /// </summary>
    public required string Id { get; init; }

    /// <summary>
    /// Tenant identifier for multi-tenancy isolation.
    /// </summary>
    public required string Tenant { get; init; }

    /// <summary>
    /// Image digest of the container this snapshot was captured from.
    /// </summary>
    [JsonPropertyName("imageDigest")]
    public required string ImageDigest { get; init; }

    /// <summary>
    /// Node identifier where the snapshot was captured.
    /// </summary>
    public string? Node { get; init; }

    /// <summary>
    /// Container ID where the process was running.
    /// </summary>
    public string? ContainerId { get; init; }

    /// <summary>
    /// Process ID at capture time.
    /// </summary>
    public int Pid { get; init; }

    /// <summary>
    /// Process entrypoint command.
    /// </summary>
    public string? Entrypoint { get; init; }

    /// <summary>
    /// Runtime type: java, dotnet, php.
    /// </summary>
    public required string RuntimeType { get; init; }

    /// <summary>
    /// Runtime version (e.g., "17.0.2", "8.0.0", "8.2.0").
    /// </summary>
    public string? RuntimeVersion { get; init; }

    /// <summary>
    /// Java classpath entries (jar paths, directories).
    /// </summary>
    [JsonPropertyName("classpath")]
    public IReadOnlyList<ClasspathEntry> Classpath { get; init; } = Array.Empty<ClasspathEntry>();

    /// <summary>
    /// .NET loaded assemblies with RID-graph resolution.
    /// </summary>
    [JsonPropertyName("loadedAssemblies")]
    public IReadOnlyList<LoadedAssemblyEntry> LoadedAssemblies { get; init; } = Array.Empty<LoadedAssemblyEntry>();

    /// <summary>
    /// PHP autoload paths from composer autoloader.
    /// </summary>
    [JsonPropertyName("autoloadPaths")]
    public IReadOnlyList<AutoloadPathEntry> AutoloadPaths { get; init; } = Array.Empty<AutoloadPathEntry>();

    /// <summary>
    /// Timestamp when the snapshot was captured.
    /// </summary>
    public DateTimeOffset CapturedAt { get; init; }

    /// <summary>
    /// Timestamp when the snapshot was stored.
    /// </summary>
    public DateTimeOffset StoredAt { get; init; }

    /// <summary>
    /// Expiration timestamp for TTL-based cleanup.
    /// </summary>
    public DateTimeOffset? ExpiresAt { get; init; }

    /// <summary>
    /// Additional annotations/metadata.
    /// </summary>
    public IReadOnlyDictionary<string, string>? Annotations { get; init; }
}

/// <summary>
/// Java classpath entry representing a JAR or directory.
/// </summary>
public sealed record ClasspathEntry
{
    /// <summary>
    /// Path to the JAR file or classpath directory.
    /// </summary>
    public required string Path { get; init; }

    /// <summary>
    /// Type: jar, directory, jmod.
    /// </summary>
    public string? Type { get; init; }

    /// <summary>
    /// SHA-256 hash of the JAR file (null for directories).
    /// </summary>
    public string? Sha256 { get; init; }

    /// <summary>
    /// Maven coordinate if resolvable (e.g., "org.springframework:spring-core:5.3.20").
    /// </summary>
    public string? MavenCoordinate { get; init; }

    /// <summary>
    /// Package URL (PURL) if resolvable.
    /// </summary>
    public string? Purl { get; init; }

    /// <summary>
    /// Size in bytes.
    /// </summary>
    public long? SizeBytes { get; init; }
}

/// <summary>
/// .NET loaded assembly entry with RID-graph context.
/// </summary>
public sealed record LoadedAssemblyEntry
{
    /// <summary>
    /// Assembly name (e.g., "System.Text.Json").
    /// </summary>
    public required string Name { get; init; }

    /// <summary>
    /// Assembly version (e.g., "8.0.0.0").
    /// </summary>
    public string? Version { get; init; }

    /// <summary>
    /// Full path to the loaded DLL.
    /// </summary>
    public required string Path { get; init; }

    /// <summary>
    /// SHA-256 hash of the assembly file.
    /// </summary>
    public string? Sha256 { get; init; }

    /// <summary>
    /// NuGet package ID if resolvable.
    /// </summary>
    public string? NuGetPackage { get; init; }

    /// <summary>
    /// NuGet package version if resolvable.
    /// </summary>
    public string? NuGetVersion { get; init; }

    /// <summary>
    /// Package URL (PURL) if resolvable.
    /// </summary>
    public string? Purl { get; init; }

    /// <summary>
    /// Runtime identifier (RID) for platform-specific assemblies.
    /// </summary>
    public string? Rid { get; init; }

    /// <summary>
    /// Whether this assembly was loaded from the shared framework.
    /// </summary>
    public bool? IsFrameworkAssembly { get; init; }

    /// <summary>
    /// Source from deps.json resolution: compile, runtime, native.
    /// </summary>
    public string? DepsSource { get; init; }
}

/// <summary>
/// PHP autoload path entry from Composer.
/// </summary>
public sealed record AutoloadPathEntry
{
    /// <summary>
    /// Namespace prefix (PSR-4) or class name (classmap).
    /// </summary>
    public string? Namespace { get; init; }

    /// <summary>
    /// Autoload type: psr-4, psr-0, classmap, files.
    /// </summary>
    public required string Type { get; init; }

    /// <summary>
    /// Path to the autoloaded file or directory.
    /// </summary>
    public required string Path { get; init; }

    /// <summary>
    /// Composer package name if resolvable.
    /// </summary>
    public string? ComposerPackage { get; init; }

    /// <summary>
    /// Composer package version if resolvable.
    /// </summary>
    public string? ComposerVersion { get; init; }

    /// <summary>
    /// Package URL (PURL) if resolvable.
    /// </summary>
    public string? Purl { get; init; }
}

/// <summary>
/// Known runtime types for proc snapshots.
/// </summary>
public static class ProcSnapshotRuntimeTypes
{
    public const string Java = "java";
    public const string DotNet = "dotnet";
    public const string Php = "php";
}