Add PHP Analyzer Plugin and Composer Lock Data Handling

- Implemented the PhpAnalyzerPlugin to analyze PHP projects.
- Created ComposerLockData class to represent data from composer.lock files.
- Developed ComposerLockReader to load and parse composer.lock files asynchronously.
- Introduced ComposerPackage class to encapsulate package details.
- Added PhpPackage class to represent PHP packages with metadata and evidence.
- Implemented PhpPackageCollector to gather packages from ComposerLockData.
- Created PhpLanguageAnalyzer to perform analysis and emit results.
- Added capability signals for known PHP frameworks and CMS.
- Developed unit tests for the PHP language analyzer and its components.
- Included sample composer.lock and expected output for testing.
- Updated project files for the new PHP analyzer library and tests.

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/LedgerDataSource.cs

@@ -1,6 +1,8 @@
+using System.Data;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using Npgsql;
+using StellaOps.Findings.Ledger.Observability;
 using StellaOps.Findings.Ledger.Options;
 
 namespace StellaOps.Findings.Ledger.Infrastructure.Postgres;
@@ -31,15 +33,26 @@ public sealed class LedgerDataSource : IAsyncDisposable
     }
 
     public Task<NpgsqlConnection> OpenConnectionAsync(string tenantId, CancellationToken cancellationToken)
-        => OpenConnectionInternalAsync(tenantId, cancellationToken);
+        => OpenConnectionInternalAsync(tenantId, "unspecified", cancellationToken);
 
-    private async Task<NpgsqlConnection> OpenConnectionInternalAsync(string tenantId, CancellationToken cancellationToken)
+    public Task<NpgsqlConnection> OpenConnectionAsync(string tenantId, string role, CancellationToken cancellationToken)
+        => OpenConnectionInternalAsync(tenantId, role, cancellationToken);
+
+    private async Task<NpgsqlConnection> OpenConnectionInternalAsync(string tenantId, string role, CancellationToken cancellationToken)
     {
         var connection = await _dataSource.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
 
         try
         {
             await ConfigureSessionAsync(connection, tenantId, cancellationToken).ConfigureAwait(false);
+            LedgerMetrics.ConnectionOpened(role);
+            connection.StateChange += (_, args) =>
+            {
+                if (args.CurrentState == ConnectionState.Closed)
+                {
+                    LedgerMetrics.ConnectionClosed(role);
+                }
+            };
         }
         catch
         {

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresAirgapImportRepository.cs

@@ -0,0 +1,94 @@
+using System.Text.Json.Nodes;
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using NpgsqlTypes;
+using StellaOps.Findings.Ledger.Hashing;
+using StellaOps.Findings.Ledger.Infrastructure.AirGap;
+
+namespace StellaOps.Findings.Ledger.Infrastructure.Postgres;
+
+public sealed class PostgresAirgapImportRepository : IAirgapImportRepository
+{
+    private const string InsertSql = """
+        INSERT INTO airgap_imports (
+            tenant_id,
+            bundle_id,
+            mirror_generation,
+            merkle_root,
+            time_anchor,
+            publisher,
+            hash_algorithm,
+            contents,
+            imported_at,
+            import_operator,
+            ledger_event_id)
+        VALUES (
+            @tenant_id,
+            @bundle_id,
+            @mirror_generation,
+            @merkle_root,
+            @time_anchor,
+            @publisher,
+            @hash_algorithm,
+            @contents,
+            @imported_at,
+            @import_operator,
+            @ledger_event_id)
+        ON CONFLICT (tenant_id, bundle_id, time_anchor)
+        DO UPDATE SET
+            merkle_root = EXCLUDED.merkle_root,
+            publisher = EXCLUDED.publisher,
+            hash_algorithm = EXCLUDED.hash_algorithm,
+            contents = EXCLUDED.contents,
+            imported_at = EXCLUDED.imported_at,
+            import_operator = EXCLUDED.import_operator,
+            ledger_event_id = EXCLUDED.ledger_event_id;
+        """;
+
+    private readonly LedgerDataSource _dataSource;
+    private readonly ILogger<PostgresAirgapImportRepository> _logger;
+
+    public PostgresAirgapImportRepository(
+        LedgerDataSource dataSource,
+        ILogger<PostgresAirgapImportRepository> logger)
+    {
+        _dataSource = dataSource ?? throw new ArgumentNullException(nameof(dataSource));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task InsertAsync(AirgapImportRecord record, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(record);
+
+        var canonicalContents = LedgerCanonicalJsonSerializer.Canonicalize(record.Contents);
+        var contentsJson = canonicalContents.ToJsonString();
+
+        await using var connection = await _dataSource.OpenConnectionAsync(record.TenantId, "airgap-import", cancellationToken).ConfigureAwait(false);
+        await using var command = new NpgsqlCommand(InsertSql, connection)
+        {
+            CommandTimeout = _dataSource.CommandTimeoutSeconds
+        };
+
+        command.Parameters.Add(new NpgsqlParameter<string>("tenant_id", record.TenantId) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("bundle_id", record.BundleId) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string?>("mirror_generation", record.MirrorGeneration) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("merkle_root", record.MerkleRoot) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<DateTimeOffset>("time_anchor", record.TimeAnchor) { NpgsqlDbType = NpgsqlDbType.TimestampTz });
+        command.Parameters.Add(new NpgsqlParameter<string?>("publisher", record.Publisher) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string?>("hash_algorithm", record.HashAlgorithm) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("contents", contentsJson) { NpgsqlDbType = NpgsqlDbType.Jsonb });
+        command.Parameters.Add(new NpgsqlParameter<DateTimeOffset>("imported_at", record.ImportedAt) { NpgsqlDbType = NpgsqlDbType.TimestampTz });
+        command.Parameters.Add(new NpgsqlParameter<string?>("import_operator", record.ImportOperator) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<Guid?>("ledger_event_id", record.LedgerEventId) { NpgsqlDbType = NpgsqlDbType.Uuid });
+
+        try
+        {
+            await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+        }
+        catch (PostgresException ex)
+        {
+            _logger.LogError(ex, "Failed to insert air-gap import for tenant {TenantId} bundle {BundleId}.", record.TenantId, record.BundleId);
+            throw;
+        }
+    }
+}

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresFindingProjectionRepository.cs

@@ -12,6 +12,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
     private const string GetProjectionSql = """
         SELECT status,
                severity,
+               risk_score,
+               risk_severity,
+               risk_profile_version,
+               risk_explanation_id,
+               risk_event_sequence,
                labels,
                current_event_id,
                explain_ref,
@@ -31,6 +36,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
             policy_version,
             status,
             severity,
+            risk_score,
+            risk_severity,
+            risk_profile_version,
+            risk_explanation_id,
+            risk_event_sequence,
             labels,
             current_event_id,
             explain_ref,
@@ -43,6 +53,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
             @policy_version,
             @status,
             @severity,
+            @risk_score,
+            @risk_severity,
+            @risk_profile_version,
+            @risk_explanation_id,
+            @risk_event_sequence,
             @labels,
             @current_event_id,
             @explain_ref,
@@ -53,6 +68,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
         DO UPDATE SET
             status = EXCLUDED.status,
             severity = EXCLUDED.severity,
+            risk_score = EXCLUDED.risk_score,
+            risk_severity = EXCLUDED.risk_severity,
+            risk_profile_version = EXCLUDED.risk_profile_version,
+            risk_explanation_id = EXCLUDED.risk_explanation_id,
+            risk_event_sequence = EXCLUDED.risk_event_sequence,
             labels = EXCLUDED.labels,
             current_event_id = EXCLUDED.current_event_id,
             explain_ref = EXCLUDED.explain_ref,
@@ -153,7 +173,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
 
     public async Task<FindingProjection?> GetAsync(string tenantId, string findingId, string policyVersion, CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(GetProjectionSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("tenant_id", tenantId);
@@ -168,11 +188,16 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
 
         var status = reader.GetString(0);
         var severity = reader.IsDBNull(1) ? (decimal?)null : reader.GetDecimal(1);
-        var labelsJson = reader.GetFieldValue<string>(2);
+        var riskScore = reader.IsDBNull(2) ? (decimal?)null : reader.GetDecimal(2);
+        var riskSeverity = reader.IsDBNull(3) ? null : reader.GetString(3);
+        var riskProfileVersion = reader.IsDBNull(4) ? null : reader.GetString(4);
+        var riskExplanationId = reader.IsDBNull(5) ? (Guid?)null : reader.GetGuid(5);
+        var riskEventSequence = reader.IsDBNull(6) ? (long?)null : reader.GetInt64(6);
+        var labelsJson = reader.GetFieldValue<string>(7);
         var labels = JsonNode.Parse(labelsJson)?.AsObject() ?? new JsonObject();
-        var currentEventId = reader.GetGuid(3);
-        var explainRef = reader.IsDBNull(4) ? null : reader.GetString(4);
-        var rationaleJson = reader.IsDBNull(5) ? string.Empty : reader.GetFieldValue<string>(5);
+        var currentEventId = reader.GetGuid(8);
+        var explainRef = reader.IsDBNull(9) ? null : reader.GetString(9);
+        var rationaleJson = reader.IsDBNull(10) ? string.Empty : reader.GetFieldValue<string>(10);
         JsonArray rationale;
         if (string.IsNullOrWhiteSpace(rationaleJson))
         {
@@ -182,8 +207,8 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
         {
             rationale = JsonNode.Parse(rationaleJson) as JsonArray ?? new JsonArray();
         }
-        var updatedAt = reader.GetFieldValue<DateTimeOffset>(6);
-        var cycleHash = reader.GetString(7);
+        var updatedAt = reader.GetFieldValue<DateTimeOffset>(11);
+        var cycleHash = reader.GetString(12);
 
         return new FindingProjection(
             tenantId,
@@ -191,6 +216,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
             policyVersion,
             status,
             severity,
+            riskScore,
+            riskSeverity,
+            riskProfileVersion,
+            riskExplanationId,
+            riskEventSequence,
             labels,
             currentEventId,
             explainRef,
@@ -203,7 +233,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
     {
         ArgumentNullException.ThrowIfNull(projection);
 
-        await using var connection = await _dataSource.OpenConnectionAsync(projection.TenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(projection.TenantId, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(UpsertProjectionSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 
@@ -212,6 +242,11 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
         command.Parameters.AddWithValue("policy_version", projection.PolicyVersion);
         command.Parameters.AddWithValue("status", projection.Status);
         command.Parameters.AddWithValue("severity", projection.Severity.HasValue ? projection.Severity.Value : (object)DBNull.Value);
+        command.Parameters.AddWithValue("risk_score", projection.RiskScore.HasValue ? projection.RiskScore.Value : (object)DBNull.Value);
+        command.Parameters.AddWithValue("risk_severity", projection.RiskSeverity ?? (object)DBNull.Value);
+        command.Parameters.AddWithValue("risk_profile_version", projection.RiskProfileVersion ?? (object)DBNull.Value);
+        command.Parameters.AddWithValue("risk_explanation_id", projection.RiskExplanationId ?? (object)DBNull.Value);
+        command.Parameters.AddWithValue("risk_event_sequence", projection.RiskEventSequence.HasValue ? projection.RiskEventSequence.Value : (object)DBNull.Value);
 
         var labelsCanonical = LedgerCanonicalJsonSerializer.Canonicalize(projection.Labels);
         var labelsJson = labelsCanonical.ToJsonString();
@@ -233,7 +268,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
     {
         ArgumentNullException.ThrowIfNull(entry);
 
-        await using var connection = await _dataSource.OpenConnectionAsync(entry.TenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(entry.TenantId, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(InsertHistorySql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 
@@ -254,7 +289,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
     {
         ArgumentNullException.ThrowIfNull(entry);
 
-        await using var connection = await _dataSource.OpenConnectionAsync(entry.TenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(entry.TenantId, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(InsertActionSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 
@@ -275,7 +310,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
 
     public async Task<ProjectionCheckpoint> GetCheckpointAsync(CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(SelectCheckpointSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("worker_id", DefaultWorkerId);
@@ -296,7 +331,7 @@ public sealed class PostgresFindingProjectionRepository : IFindingProjectionRepo
     {
         ArgumentNullException.ThrowIfNull(checkpoint);
 
-        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(UpsertCheckpointSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventRepository.cs

@@ -96,7 +96,7 @@ public sealed class PostgresLedgerEventRepository : ILedgerEventRepository
 
     public async Task<LedgerEventRecord?> GetByEventIdAsync(string tenantId, Guid eventId, CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "writer-read", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(SelectByEventIdSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("tenant_id", tenantId);
@@ -113,7 +113,7 @@ public sealed class PostgresLedgerEventRepository : ILedgerEventRepository
 
     public async Task<LedgerChainHead?> GetChainHeadAsync(string tenantId, Guid chainId, CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "writer-read", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(SelectChainHeadSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("tenant_id", tenantId);
@@ -133,7 +133,7 @@ public sealed class PostgresLedgerEventRepository : ILedgerEventRepository
 
     public async Task AppendAsync(LedgerEventRecord record, CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(record.TenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(record.TenantId, "writer", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(InsertEventSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 
@@ -236,7 +236,7 @@ public sealed class PostgresLedgerEventRepository : ILedgerEventRepository
              ORDER BY recorded_at DESC
             """;
 
-        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "writer-read", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(sql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("tenant_id", tenantId);

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresLedgerEventStream.cs

@@ -57,7 +57,7 @@ public sealed class PostgresLedgerEventStream : ILedgerEventStream
 
         var records = new List<LedgerEventRecord>(batchSize);
 
-        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(string.Empty, "projector", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(ReadEventsSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
         command.Parameters.AddWithValue("last_recorded_at", checkpoint.LastRecordedAt);

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresMerkleAnchorRepository.cs

@@ -55,7 +55,7 @@ public sealed class PostgresMerkleAnchorRepository : IMerkleAnchorRepository
         string? anchorReference,
         CancellationToken cancellationToken)
     {
-        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, cancellationToken).ConfigureAwait(false);
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "anchor", cancellationToken).ConfigureAwait(false);
         await using var command = new NpgsqlCommand(InsertAnchorSql, connection);
         command.CommandTimeout = _dataSource.CommandTimeoutSeconds;
 

src/Findings/StellaOps.Findings.Ledger/Infrastructure/Postgres/PostgresOrchestratorExportRepository.cs

@@ -0,0 +1,146 @@
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using NpgsqlTypes;
+using StellaOps.Findings.Ledger.Infrastructure.Exports;
+
+namespace StellaOps.Findings.Ledger.Infrastructure.Postgres;
+
+public sealed class PostgresOrchestratorExportRepository : IOrchestratorExportRepository
+{
+    private const string UpsertSql = """
+        INSERT INTO orchestrator_exports (
+            tenant_id,
+            run_id,
+            job_type,
+            artifact_hash,
+            policy_hash,
+            started_at,
+            completed_at,
+            status,
+            manifest_path,
+            logs_path,
+            merkle_root,
+            created_at)
+        VALUES (
+            @tenant_id,
+            @run_id,
+            @job_type,
+            @artifact_hash,
+            @policy_hash,
+            @started_at,
+            @completed_at,
+            @status,
+            @manifest_path,
+            @logs_path,
+            @merkle_root,
+            @created_at)
+        ON CONFLICT (tenant_id, run_id)
+        DO UPDATE SET
+            job_type = EXCLUDED.job_type,
+            artifact_hash = EXCLUDED.artifact_hash,
+            policy_hash = EXCLUDED.policy_hash,
+            started_at = EXCLUDED.started_at,
+            completed_at = EXCLUDED.completed_at,
+            status = EXCLUDED.status,
+            manifest_path = EXCLUDED.manifest_path,
+            logs_path = EXCLUDED.logs_path,
+            merkle_root = EXCLUDED.merkle_root,
+            created_at = EXCLUDED.created_at;
+        """;
+
+    private const string SelectByArtifactSql = """
+        SELECT run_id,
+               job_type,
+               artifact_hash,
+               policy_hash,
+               started_at,
+               completed_at,
+               status,
+               manifest_path,
+               logs_path,
+               merkle_root,
+               created_at
+          FROM orchestrator_exports
+         WHERE tenant_id = @tenant_id
+           AND artifact_hash = @artifact_hash
+         ORDER BY completed_at DESC NULLS LAST, started_at DESC;
+        """;
+
+    private readonly LedgerDataSource _dataSource;
+    private readonly ILogger<PostgresOrchestratorExportRepository> _logger;
+
+    public PostgresOrchestratorExportRepository(
+        LedgerDataSource dataSource,
+        ILogger<PostgresOrchestratorExportRepository> logger)
+    {
+        _dataSource = dataSource ?? throw new ArgumentNullException(nameof(dataSource));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+    }
+
+    public async Task InsertAsync(OrchestratorExportRecord record, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(record);
+
+        await using var connection = await _dataSource.OpenConnectionAsync(record.TenantId, "orchestrator-export", cancellationToken).ConfigureAwait(false);
+        await using var command = new NpgsqlCommand(UpsertSql, connection)
+        {
+            CommandTimeout = _dataSource.CommandTimeoutSeconds
+        };
+
+        command.Parameters.Add(new NpgsqlParameter<string>("tenant_id", record.TenantId) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<Guid>("run_id", record.RunId) { NpgsqlDbType = NpgsqlDbType.Uuid });
+        command.Parameters.Add(new NpgsqlParameter<string>("job_type", record.JobType) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("artifact_hash", record.ArtifactHash) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("policy_hash", record.PolicyHash) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<DateTimeOffset>("started_at", record.StartedAt) { NpgsqlDbType = NpgsqlDbType.TimestampTz });
+        command.Parameters.Add(new NpgsqlParameter<DateTimeOffset?>("completed_at", record.CompletedAt) { NpgsqlDbType = NpgsqlDbType.TimestampTz });
+        command.Parameters.Add(new NpgsqlParameter<string>("status", record.Status) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string?>("manifest_path", record.ManifestPath) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string?>("logs_path", record.LogsPath) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("merkle_root", record.MerkleRoot) { NpgsqlDbType = NpgsqlDbType.Char });
+        command.Parameters.Add(new NpgsqlParameter<DateTimeOffset>("created_at", record.CreatedAt) { NpgsqlDbType = NpgsqlDbType.TimestampTz });
+
+        try
+        {
+            await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+        }
+        catch (PostgresException ex)
+        {
+            _logger.LogError(ex, "Failed to upsert orchestrator export for tenant {TenantId} run {RunId}.", record.TenantId, record.RunId);
+            throw;
+        }
+    }
+
+    public async Task<IReadOnlyList<OrchestratorExportRecord>> GetByArtifactAsync(string tenantId, string artifactHash, CancellationToken cancellationToken)
+    {
+        var results = new List<OrchestratorExportRecord>();
+
+        await using var connection = await _dataSource.OpenConnectionAsync(tenantId, "orchestrator-export", cancellationToken).ConfigureAwait(false);
+        await using var command = new NpgsqlCommand(SelectByArtifactSql, connection)
+        {
+            CommandTimeout = _dataSource.CommandTimeoutSeconds
+        };
+        command.Parameters.Add(new NpgsqlParameter<string>("tenant_id", tenantId) { NpgsqlDbType = NpgsqlDbType.Text });
+        command.Parameters.Add(new NpgsqlParameter<string>("artifact_hash", artifactHash) { NpgsqlDbType = NpgsqlDbType.Text });
+
+        await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false);
+        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
+        {
+            results.Add(new OrchestratorExportRecord(
+                TenantId: tenantId,
+                RunId: reader.GetGuid(0),
+                JobType: reader.GetString(1),
+                ArtifactHash: reader.GetString(2),
+                PolicyHash: reader.GetString(3),
+                StartedAt: reader.GetFieldValue<DateTimeOffset>(4),
+                CompletedAt: reader.IsDBNull(5) ? (DateTimeOffset?)null : reader.GetFieldValue<DateTimeOffset>(5),
+                Status: reader.GetString(6),
+                ManifestPath: reader.IsDBNull(7) ? null : reader.GetString(7),
+                LogsPath: reader.IsDBNull(8) ? null : reader.GetString(8),
+                MerkleRoot: reader.GetString(9),
+                CreatedAt: reader.GetFieldValue<DateTimeOffset>(10)));
+        }
+
+        return results;
+    }
+}