Resolve Concelier/Excititor merge conflicts

src/StellaOps.Concelier.Connector.Common/State/SourceStateSeedModels.cs

@@ -0,0 +1,159 @@
+using StellaOps.Concelier.Connector.Common;
+
+namespace StellaOps.Concelier.Connector.Common.State;
+
+/// <summary>
+/// Describes a raw upstream document that should be persisted for a connector during seeding.
+/// </summary>
+public sealed record SourceStateSeedDocument
+{
+    /// <summary>
+    /// Absolute source URI. Must match the connector's upstream document identifier.
+    /// </summary>
+    public string Uri { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Raw document payload. Required when creating or replacing a document.
+    /// </summary>
+    public byte[] Content { get; init; } = Array.Empty<byte>();
+
+    /// <summary>
+    /// Optional explicit document identifier. When provided it overrides auto-generated IDs.
+    /// </summary>
+    public Guid? DocumentId { get; init; }
+
+    /// <summary>
+    /// MIME type for the document payload.
+    /// </summary>
+    public string? ContentType { get; init; }
+
+    /// <summary>
+    /// Status assigned to the document. Defaults to <see cref="DocumentStatuses.PendingParse"/>.
+    /// </summary>
+    public string Status { get; init; } = DocumentStatuses.PendingParse;
+
+    /// <summary>
+    /// Optional HTTP-style headers persisted alongside the raw document.
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? Headers { get; init; }
+
+    /// <summary>
+    /// Source metadata (connector specific) persisted alongside the raw document.
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? Metadata { get; init; }
+
+    /// <summary>
+    /// Upstream ETag value, if available.
+    /// </summary>
+    public string? Etag { get; init; }
+
+    /// <summary>
+    /// Upstream last-modified timestamp, if available.
+    /// </summary>
+    public DateTimeOffset? LastModified { get; init; }
+
+    /// <summary>
+    /// Optional document expiration. When set a TTL will purge the raw payload after the configured retention.
+    /// </summary>
+    public DateTimeOffset? ExpiresAt { get; init; }
+
+    /// <summary>
+    /// Fetch timestamp stamped onto the document. Defaults to the seed completion timestamp.
+    /// </summary>
+    public DateTimeOffset? FetchedAt { get; init; }
+
+    /// <summary>
+    /// When true, the document ID will be appended to the connector cursor's <c>pendingDocuments</c> set.
+    /// </summary>
+    public bool AddToPendingDocuments { get; init; } = true;
+
+    /// <summary>
+    /// When true, the document ID will be appended to the connector cursor's <c>pendingMappings</c> set.
+    /// </summary>
+    public bool AddToPendingMappings { get; init; }
+
+    /// <summary>
+    /// Optional identifiers that should be recorded on the cursor to avoid duplicate ingestion.
+    /// </summary>
+    public IReadOnlyCollection<string>? KnownIdentifiers { get; init; }
+}
+
+/// <summary>
+/// Cursor updates that should accompany seeded documents.
+/// </summary>
+public sealed record SourceStateSeedCursor
+{
+    /// <summary>
+    /// Optional <c>pendingDocuments</c> additions expressed as document IDs.
+    /// </summary>
+    public IReadOnlyCollection<Guid>? PendingDocuments { get; init; }
+
+    /// <summary>
+    /// Optional <c>pendingMappings</c> additions expressed as document IDs.
+    /// </summary>
+    public IReadOnlyCollection<Guid>? PendingMappings { get; init; }
+
+    /// <summary>
+    /// Optional known advisory identifiers to merge with the cursor.
+    /// </summary>
+    public IReadOnlyCollection<string>? KnownAdvisories { get; init; }
+
+    /// <summary>
+    /// Upstream window watermark tracked by connectors that rely on last-modified cursors.
+    /// </summary>
+    public DateTimeOffset? LastModifiedCursor { get; init; }
+
+    /// <summary>
+    /// Optional fetch timestamp used by connectors that track the last polling instant.
+    /// </summary>
+    public DateTimeOffset? LastFetchAt { get; init; }
+
+    /// <summary>
+    /// Additional cursor fields (string values) to merge.
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? Additional { get; init; }
+}
+
+/// <summary>
+/// Seeding specification describing the source, documents, and cursor edits to apply.
+/// </summary>
+public sealed record SourceStateSeedSpecification
+{
+    /// <summary>
+    /// Source/connector name (e.g. <c>vndr.msrc</c>).
+    /// </summary>
+    public string Source { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Documents that should be inserted or replaced before the cursor update.
+    /// </summary>
+    public IReadOnlyList<SourceStateSeedDocument> Documents { get; init; } = Array.Empty<SourceStateSeedDocument>();
+
+    /// <summary>
+    /// Cursor adjustments applied after documents are persisted.
+    /// </summary>
+    public SourceStateSeedCursor? Cursor { get; init; }
+
+    /// <summary>
+    /// Connector-level known advisory identifiers to merge into the cursor.
+    /// </summary>
+    public IReadOnlyCollection<string>? KnownAdvisories { get; init; }
+
+    /// <summary>
+    /// Optional completion timestamp. Defaults to the processor's time provider.
+    /// </summary>
+    public DateTimeOffset? CompletedAt { get; init; }
+}
+
+/// <summary>
+/// Result returned after seeding completes.
+/// </summary>
+public sealed record SourceStateSeedResult(
+    int DocumentsProcessed,
+    int PendingDocumentsAdded,
+    int PendingMappingsAdded,
+    IReadOnlyCollection<Guid> DocumentIds,
+    IReadOnlyCollection<Guid> PendingDocumentIds,
+    IReadOnlyCollection<Guid> PendingMappingIds,
+    IReadOnlyCollection<string> KnownAdvisoriesAdded,
+    DateTimeOffset CompletedAt);