| | | 1 | | using RoleRadar.Domain.Audit; |
| | | 2 | | using RoleRadar.Domain.Notes; |
| | | 3 | | |
| | | 4 | | namespace RoleRadar.Application.Abstractions; |
| | | 5 | | |
| | | 6 | | public sealed record StoreReadinessStatus( |
| | | 7 | | bool IsReady, |
| | | 8 | | string Endpoint, |
| | | 9 | | string ReplicaSet, |
| | | 10 | | double LatencyMs, |
| | | 11 | | string? RemediationMessage = null); |
| | | 12 | | |
| | 280 | 13 | | public sealed record NoteSearchCriteria( |
| | 280 | 14 | | string OwnerId, |
| | 2154 | 15 | | string? Query = null, |
| | 362 | 16 | | IReadOnlyList<string>? Tags = null, |
| | 460 | 17 | | string? Area = null, |
| | 278 | 18 | | bool IncludeArchived = false, |
| | 832 | 19 | | int Limit = 20); |
| | | 20 | | |
| | | 21 | | public sealed record NoteSearchHit( |
| | | 22 | | Note Note, |
| | | 23 | | double Score, |
| | | 24 | | string Snippet); |
| | | 25 | | |
| | | 26 | | public sealed record NoteWriteOutcome( |
| | | 27 | | Note Note, |
| | | 28 | | AuditLogEntry AuditEntry, |
| | | 29 | | NoteRevision? Revision = null); |
| | | 30 | | |
| | | 31 | | public sealed record UpsertImportedSectionRequest( |
| | | 32 | | string OwnerId, |
| | | 33 | | string SourceFileId, |
| | | 34 | | string HeadingPath, |
| | | 35 | | int OccurrenceIndex, |
| | | 36 | | int SectionOrderIndex, |
| | | 37 | | string Title, |
| | | 38 | | string Body, |
| | | 39 | | IReadOnlyList<string> Tags, |
| | | 40 | | string Area, |
| | | 41 | | ProvenanceMarker Provenance, |
| | | 42 | | string ResolvedDefaultDate, |
| | | 43 | | string Actor, |
| | | 44 | | DateTime OccurredAtUtc); |
| | | 45 | | |
| | | 46 | | public interface INoteRepository |
| | | 47 | | { |
| | | 48 | | /// <summary> |
| | | 49 | | /// Verifies that the backing MongoDB replica set is reachable and ready for transactions within <=3s (under the |
| | | 50 | | /// Returns ErrorCode.DatastoreOffline with the exact start-services command when unreachable. |
| | | 51 | | /// </summary> |
| | | 52 | | Task<Result<StoreReadinessStatus>> CheckReadinessAsync( |
| | | 53 | | CancellationToken cancellationToken = default); |
| | | 54 | | |
| | | 55 | | /// <summary> |
| | | 56 | | /// Executes the supplied work within a single MongoDB multi-document ACID transaction across notes, note_revisions, |
| | | 57 | | /// rolling back completely if the returned Result is a failure or an unexpected fault occurs. |
| | | 58 | | /// Invoked by TransactionCommandDecorator. |
| | | 59 | | /// </summary> |
| | | 60 | | Task<Result<TResponse>> ExecuteInTransactionAsync<TResponse>( |
| | | 61 | | Func<INoteTransactionContext, CancellationToken, Task<Result<TResponse>>> work, |
| | | 62 | | CancellationToken cancellationToken = default); |
| | | 63 | | |
| | | 64 | | /// <summary> |
| | | 65 | | /// Retrieves a single Note by owner and ID (including archived notes), or ResultError(ErrorCode.NotFound). |
| | | 66 | | /// </summary> |
| | | 67 | | Task<Result<Note>> GetByIdAsync( |
| | | 68 | | string ownerId, |
| | | 69 | | Guid noteId, |
| | | 70 | | CancellationToken cancellationToken = default); |
| | | 71 | | |
| | | 72 | | /// <summary> |
| | | 73 | | /// Searches notes for the given owner using case-insensitive, whole-word stemmed text search (supporting quoted phr |
| | | 74 | | /// ANDed tag and area filters, and archived-inclusion toggle, ordered by relevance descending, then updated_at desc |
| | | 75 | | /// </summary> |
| | | 76 | | Task<Result<IReadOnlyList<NoteSearchHit>>> SearchAsync( |
| | | 77 | | NoteSearchCriteria criteria, |
| | | 78 | | CancellationToken cancellationToken = default); |
| | | 79 | | |
| | | 80 | | /// <summary> |
| | | 81 | | /// Retrieves all previously imported notes for a given owner and source file ID, ordered by section_order_index asc |
| | | 82 | | /// </summary> |
| | | 83 | | Task<Result<IReadOnlyList<Note>>> GetImportedBySourceFileAsync( |
| | | 84 | | string ownerId, |
| | | 85 | | string sourceFileId, |
| | | 86 | | CancellationToken cancellationToken = default); |
| | | 87 | | |
| | | 88 | | /// <summary> |
| | | 89 | | /// Retrieves the append-only revision history for a Note, ordered by revision_number ascending. |
| | | 90 | | /// </summary> |
| | | 91 | | Task<Result<IReadOnlyList<NoteRevision>>> GetRevisionsAsync( |
| | | 92 | | string ownerId, |
| | | 93 | | Guid noteId, |
| | | 94 | | CancellationToken cancellationToken = default); |
| | | 95 | | |
| | | 96 | | /// <summary> |
| | | 97 | | /// Retrieves the append-only audit log entries for a Note (or all notes for the owner when noteId is null), |
| | | 98 | | /// ordered chronologically. |
| | | 99 | | /// </summary> |
| | | 100 | | Task<Result<IReadOnlyList<AuditLogEntry>>> GetAuditEntriesAsync( |
| | | 101 | | string ownerId, |
| | | 102 | | Guid? noteId = null, |
| | | 103 | | CancellationToken cancellationToken = default); |
| | | 104 | | } |
| | | 105 | | |
| | | 106 | | public interface INoteTransactionContext |
| | | 107 | | { |
| | | 108 | | /// <summary> |
| | | 109 | | /// Atomically inserts a new Note and its AuditLogEntry ("note_create") inside the active transaction. |
| | | 110 | | /// </summary> |
| | | 111 | | Task<Result<NoteWriteOutcome>> CreateAsync( |
| | | 112 | | Note note, |
| | | 113 | | AuditLogEntry auditEntry, |
| | | 114 | | CancellationToken cancellationToken = default); |
| | | 115 | | |
| | | 116 | | /// <summary> |
| | | 117 | | /// Atomically appends markdown text to an existing Note on the server side without requiring a caller version token |
| | | 118 | | /// rotates the note's version token, and inserts an AuditLogEntry ("note_append") recording the appended text and |
| | | 119 | | /// resulting version token. MUST NOT insert a NoteRevision snapshot. |
| | | 120 | | /// </summary> |
| | | 121 | | Task<Result<NoteWriteOutcome>> AppendAsync( |
| | | 122 | | string ownerId, |
| | | 123 | | Guid noteId, |
| | | 124 | | string textToAppend, |
| | | 125 | | string actor, |
| | | 126 | | DateTime occurredAtUtc, |
| | | 127 | | CancellationToken cancellationToken = default); |
| | | 128 | | |
| | | 129 | | /// <summary> |
| | | 130 | | /// Atomically verifies the caller's expected VersionToken (returning ErrorCode.StaleVersionToken on mismatch), |
| | | 131 | | /// inserts a full prior-body NoteRevision ("replace-section"), updates the Note body and rotates its VersionToken, |
| | | 132 | | /// and inserts an AuditLogEntry ("note_replace_section") referencing the new NoteRevisionId. |
| | | 133 | | /// </summary> |
| | | 134 | | Task<Result<NoteWriteOutcome>> ReplaceSectionAsync( |
| | | 135 | | Note updatedNote, |
| | | 136 | | Guid expectedVersionToken, |
| | | 137 | | NoteRevision priorBodyRevision, |
| | | 138 | | AuditLogEntry auditEntry, |
| | | 139 | | CancellationToken cancellationToken = default); |
| | | 140 | | |
| | | 141 | | /// <summary> |
| | | 142 | | /// Atomically marks an existing Note as Archived without altering its body or revisions, rotates its VersionToken, |
| | | 143 | | /// and inserts an AuditLogEntry ("note_archive"). |
| | | 144 | | /// Note: The MCP tool and ArchiveNoteCommand take only the Note ID (no caller VersionToken is required); |
| | | 145 | | /// ArchiveNoteCommandHandler reads the Note inside the active transaction and passes its current note.VersionToken |
| | | 146 | | /// as expectedVersionToken to guard the in-transaction update. |
| | | 147 | | /// </summary> |
| | | 148 | | Task<Result<NoteWriteOutcome>> ArchiveAsync( |
| | | 149 | | Note archivedNote, |
| | | 150 | | Guid expectedVersionToken, |
| | | 151 | | AuditLogEntry auditEntry, |
| | | 152 | | CancellationToken cancellationToken = default); |
| | | 153 | | |
| | | 154 | | /// <summary> |
| | | 155 | | /// Atomically persists an imported section inside the active transaction: |
| | | 156 | | /// - If creating: inserts Note + AuditLogEntry ("import_create", with resolved_default_date). |
| | | 157 | | /// - If overwriting an existing imported note whose current_body_hash == last_imported_body_hash: inserts a full pr |
| | | 158 | | /// NoteRevision ("import-overwrite"), updates Note, and inserts AuditLogEntry ("import_overwrite", referencing No |
| | | 159 | | /// - If current_body_hash != last_imported_body_hash: returns ErrorCode.ImportConflict without modifying the stored |
| | | 160 | | /// </summary> |
| | | 161 | | Task<Result<NoteWriteOutcome>> UpsertImportedSectionAsync( |
| | | 162 | | UpsertImportedSectionRequest request, |
| | | 163 | | CancellationToken cancellationToken = default); |
| | | 164 | | } |