=== Summary: 675 files | 7 generated | 484 fresh | 4605 untracked | 4268 adopted | 355 marked | 466 validated-ok | 2+0 stale (sig+body) | 0 skipped | 0 failed | elapsed 11:08:11.442 (40091.44s) ===

2026-06-28 02:50:05 -07:00
parent a19fb90902
commit 586f02a2ca
654 changed files with 5260 additions and 0 deletions
@@ -14,6 +14,7 @@ namespace adas_core.Application.Customizations.BD;
 /// <remarks>
 /// This type is instantiated with a primary constructor that accepts an <see cref="IServiceProvider"/> to resolve its dependencies.
 /// </remarks>
+/// <!-- aidoc:v1 sig=c3598e8 -->
 public class CalculatedObservations(IServiceProvider serviceProvider) : ICalculatedObservations
 {
    private readonly ILogger<CalculatedObservations> _logger =
@@ -29,6 +30,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation to map.</param>
    /// <param name="onlyByName">Indicates whether the mapping should match observations by name only.</param>
    /// <returns>A <see cref="Task{T}"/> containing the provided observation.</returns>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_returns
+    ///      "The method returns Task<T?> (nullable), but the documentation references Task{T} (non-nullable Task<T>)." -->
    public Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        return Task.FromResult(obs)!;
@@ -39,6 +42,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="treatment">The patient treatment instance to map.</param>
    /// <returns>A completed <see cref="Task{PatientTreatment}"/> containing the provided treatment.</returns>
+    /// <!-- aidoc:v1 sig=adce250 body=cf46cd2 -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        return Task.FromResult(treatment);
@@ -49,6 +53,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="diagnosis">The <see cref="PatientDiagnosis"/> instance to map.</param>
    /// <returns>A <see cref="Task{TResult}"/> containing the provided <see cref="PatientDiagnosis"/>.</returns>
+    /// <!-- aidoc:v1 sig=8ddf601 body=ad326e6 -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        return Task.FromResult(diagnosis);
@@ -59,6 +64,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pumpObservation">The pump observation to be mapped.</param>
    /// <returns>The mapped pump observation.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=9b6ad6e -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        if (pumpObservation.Code == "IHE PCD-04")
@@ -71,6 +77,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="activeMedicines">The list of active medicines associated with the patient.</param>
    /// <param name="patientId">The unique identifier of the patient for whom the observations are calculated.</param>
+    /// <!-- aidoc:v1 sig=b7a50a4 body=6805ef5 -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -81,6 +88,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient whose active bolus is being calculated.</param>
    /// <returns>A task that represents the asynchronous calculation of the active bolus.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary and returns description state that the method 'calculates' the active bolus, but the body only returns Task.CompletedTask and performs no calculation." -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -92,6 +101,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="id">The unique <see cref="ObjectId"/> identifier of the patient whose active treatments are being requested.</param>
    /// <returns>A task that represents the asynchronous operation, containing an <see cref="IEnumerable{PatientTreatment}"/> of nullable <see cref="PatientTreatment"/> entries for the patient's active treatments.</returns>
    /// <exception cref="NotImplementedException">Thrown to indicate that the method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=db74f82 body=bfa6f2f -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        throw new NotImplementedException();
@@ -103,6 +113,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="newObservation">The new patient observation to be reconciled against the last stored observation.</param>
    /// <returns>A task that yields the time-corrected <see cref="PatientObservation"/>, or <c>null</c> when no correction is required or no prior observation exists.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=cb71754 body=bfa6f2f -->
    public Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        throw new NotImplementedException();
@@ -114,6 +125,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to be pre-mapped before insertion.</param>
    /// <returns>A task containing the provided list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -126,6 +138,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="alarmToInsert">The source alarm to be inserted/mapped into the observation.</param>
    /// <returns>A <see cref="Task{PatientObservation}"/> that represents the asynchronous mapping operation, returning the resulting patient observation.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=405db8e body=bfa6f2f -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        throw new NotImplementedException();
@@ -139,6 +152,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="code">The optional alarm code that categorizes the alarm; may be null.</param>
    /// <returns>A task that represents the asynchronous alarm sending operation.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -152,6 +166,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pumpObservation">The pump observation containing the alarm state, type, timestamps, and identifiers used to build the alarm patient observation.</param>
    /// <returns>A completed <see cref="Task"/> representing the insert operation, which never faults since exceptions are caught internally.</returns>
+    /// <!-- aidoc:v1 sig=8716f6b body=6590257 -->
    private Task CreatePumpAlarmObservation(PumpObservation pumpObservation)
    {
        PatientObservation patientObservationAlarm = new()
@@ -14,6 +14,7 @@ namespace adas_core.Application.Customizations.CHUO;
 /// <remarks>
 /// Instances are constructed with an <see cref="IServiceProvider"/> used to resolve dependencies required by the implementation.
 /// </remarks>
+/// <!-- aidoc:v1 sig=c3598e8 -->
 public class CalculatedObservations(IServiceProvider serviceProvider) : ICalculatedObservations
 {
    private readonly ILogger<CalculatedObservations> _logger =
@@ -23,6 +24,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// Asynchronously calculates the active bolus for the specified patient.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient for whom the active bolus is being calculated.</param>
+    /// <!-- aidoc:v1 sig=7d38721 body=6805ef5 -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -33,6 +35,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A <see cref="Task{PumpObservation}"/> containing the provided pump observation.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -43,6 +46,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="activeMedicines">The list of medicines currently active for the patient.</param>
    /// <param name="patientId">The identifier of the patient for whom the observation is calculated.</param>
+    /// <!-- aidoc-review:v1 severity=low kind=stale_summary
+    ///      "Method body returns Task.CompletedTask and does not actually perform any medicine observation calculation; the summary describes intended/pending behavior." -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -55,6 +60,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="newObservation">The new patient observation to compare and reconcile against the last stored observation.</param>
    /// <returns>A task that yields the corrected <see cref="PatientObservation"/>, or <c>null</c> when no time inconsistency is found.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=cb71754 body=bfa6f2f -->
    public Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        throw new NotImplementedException();
@@ -66,6 +72,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="id">The unique identifier of the patient whose active treatments are being requested.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains a collection of nullable <see cref="PatientTreatment"/> objects representing the patient's active treatments.</returns>
    /// <exception cref="NotImplementedException">Thrown to indicate that the method has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=db74f82 body=bfa6f2f -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        throw new NotImplementedException();
@@ -77,6 +84,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation to map.</param>
    /// <param name="onlyByName">Indicates whether mapping should be performed by name only.</param>
    /// <returns>A task containing the provided observation.</returns>
+    /// <!-- aidoc:v1 sig=21d06c4 body=8f6255b -->
    public Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        _logger.LogTrace("Mapping {name} observation {obs}", obs.Name, obs);
@@ -91,6 +99,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="treatment">The patient treatment to be mapped.</param>
    /// <returns>A task that represents the asynchronous mapping operation, containing the resulting <see cref="PatientTreatment"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown when the method is invoked, as the mapping has not been implemented.</exception>
+    /// <!-- aidoc:v1 sig=adce250 body=bfa6f2f -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        throw new NotImplementedException();
@@ -102,6 +111,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="diagnosis">The patient diagnosis to be mapped.</param>
    /// <returns>A task representing the asynchronous operation, containing the mapped <see cref="PatientDiagnosis"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown because the mapping logic has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=8ddf601 body=bfa6f2f -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        throw new NotImplementedException();
@@ -113,6 +123,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to be pre-mapped prior to insertion.</param>
    /// <returns>A completed task containing the provided list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -124,6 +135,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The existing patient observation to be returned.</param>
    /// <param name="alarmToInsert">The alarm to be associated with the observation (currently not applied).</param>
    /// <returns>A completed <see cref="Task{PatientObservation}"/> containing the original observation.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -135,6 +147,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation that triggers the alarm.</param>
    /// <param name="name">The name of the alarm to send.</param>
    /// <param name="code">The optional alarm code providing additional classification for the alarm.</param>
+    /// <!-- aidoc-review:v1 severity=low kind=missing_returns
+    ///      "Method returns Task but no <returns> tag is present to describe the asynchronous result." -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        return Task.CompletedTask;
@@ -17,6 +17,7 @@ namespace adas_core.Application.Customizations.H12O.UCIN;
 /// raw observations and active <see cref="PatientTreatment"/> entries, using the catalogue of
 /// codes, groups, and types configured in <see cref="ApiSettings"/>.
 /// </summary>
+/// <!-- aidoc:v1 sig=1b16cfc -->
 public class CalculatedObservations : ICalculatedObservations
 {
    private readonly List<string> _complexityObservations =
@@ -87,6 +88,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// ONi, ventilation modes, ECMO, and notes indicating medication) from <see cref="ApiSettings"/>.
    /// </summary>
    /// <param name="serviceProvider">The application's service provider used to resolve the required dependencies and configuration.</param>
+    /// <!-- aidoc-review:v1 severity=low kind=stale_summary
+    ///      "The summary lists the configured catalogues loaded from ApiSettings but omits SurgeryText, which is also loaded in the constructor." -->
    public CalculatedObservations(IServiceProvider serviceProvider)
    {
        _observationService = serviceProvider.GetRequiredService<Lazy<IObservationService>>(); //observationService;
@@ -159,6 +162,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// A <see cref="Task{T}"/> that resolves to the (possibly transformed) observation, or
    /// <see langword="null"/> when the input observation has no name.
    /// </returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "The documentation states the method resolves to null 'when the input observation has no name', but the early-exit branch returns the original `obs`, not null." -->
    public async Task<T?> Map<T>(T obs, bool onlyByName) where T : BasePatientObservation
    {
        // Early exit: if the observation has no name, there's nothing to map
@@ -244,6 +249,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="treatment">The <see cref="PatientTreatment"/> to be mapped.</param>
    /// <returns>A task that represents the asynchronous mapping operation. The task result contains the processed <see cref="PatientTreatment"/>.</returns>
    /// <exception cref="ArgumentNullException">Thrown when the <paramref name="treatment"/> parameter is <c>null</c>.</exception>
+    /// <!-- aidoc-review:v1 severity=high kind=extra_exception
+    ///      "ArgumentNullException is documented but the method body never throws it; no null check exists for the treatment parameter, so a null argument would result in a NullReferenceException, not ArgumentNullException." -->
    public async Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        if (treatment.SingleDose)
@@ -316,6 +323,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A task containing the same <see cref="PumpObservation"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -330,6 +338,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="activeMedicines">The list of active <see cref="Medicine"/> instances currently associated with the patient.</param>
    /// <param name="patientId">The unique identifier of the patient.</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=299c0fe body=f6867d8 -->
    public async Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        await CalculateMedicineObservation(activeMedicines, [], new PatientTreatment { PatientId = patientId });
@@ -342,6 +351,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient.</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=2aadb2d body=f1796c6 -->
    public async Task CalculateActiveBolus(ObjectId patientId)
    {
        // SIN RXA
@@ -395,6 +405,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="id">The unique identifier of the patient.</param>
    /// <returns>A collection of active <see cref="PatientTreatment"/> objects for the patient.</returns>
+    /// <!-- aidoc:v1 sig=1c9e799 body=2a62eb7 -->
    public async Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        var activeTreatments = await _treatmentService.Value.GetActiveTreatmentsByPatient(id);
@@ -409,6 +420,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="diagnosis">The <see cref="PatientDiagnosis"/> to map.</param>
    /// <returns>A task containing the same <see cref="PatientDiagnosis"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=8ddf601 body=ad326e6 -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        return Task.FromResult(diagnosis);
@@ -425,6 +437,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// A task that represents the asynchronous operation. The task result contains the fixed
    /// <see cref="PatientObservation"/> if the input had a valid name; otherwise, <see langword="null"/>.
    /// </returns>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_summary
+    ///      "The summary states the trigger is when the new observation arrives with the 'same (down-to-the-second) timestamp', but the code's DateTime.Compare >= 0 condition also triggers the shift when the new observation's truncated time is strictly earlier than the last observation's." -->
    public async Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        if (string.IsNullOrEmpty(newObservation.Name))
@@ -460,6 +474,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to be pre-mapped.</param>
    /// <returns>A task containing the original list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -473,6 +488,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation that triggered the alarm.</param>
    /// <param name="alarmToInsert">The alarm metadata to be inserted alongside the observation.</param>
    /// <returns>A task containing the same <see cref="PatientObservation"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -487,6 +503,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="code">The optional alarm code from <see cref="AlarmEnum.Name"/>.</param>
    /// <returns>Never returns a result.</returns>
    /// <exception cref="NotImplementedException">Always thrown because alarm dispatch is not implemented in the UCIN customization.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -501,6 +518,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <returns>A task that represents the asynchronous insert operation.</returns>
    /// <exception cref="InvalidCastException">Thrown when <paramref name="obs"/> cannot be cast to <see cref="PatientObservation"/>.</exception>
    /// <exception cref="Exception">Rethrown after the underlying exception is written to the console for diagnostics.</exception>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_summary
+    ///      "Summary states 'Errors are logged' but the code uses Console.WriteLine for exception output, not the _logger. The companion <exception> tag correctly describes console output, so the summary is mildly inconsistent with the actual behavior." -->
    public async Task CheckSurgeryExpired(BasePatientObservation obs)
    {
        try
@@ -536,6 +555,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation expected to be a <see cref="PatientObservation"/>.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the (possibly time-shifted) base patient observation.</returns>
+    /// <!-- aidoc:v1 sig=02a8359 body=9a6b741 -->
    public async Task<BasePatientObservation> CheckObsExistsAndIncrementTime(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -559,6 +579,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation expected to be a <see cref="PatientObservation"/>.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the (possibly time-shifted) base patient observation.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary claims the method is for 'temperature observations', but the code contains no temperature-specific logic — it works for any observation type passed in, using whatever Name is on the observation." -->
    public async Task<BasePatientObservation> CheckObsWithSameTimeExistsAndIncrementTime(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -579,6 +601,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The observation that triggered the calculation (one of <c>AirPressure_Mean</c>, <c>FiO2</c>, or <c>PaO2</c>).</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=3429ff2 body=103e384 -->
    public async Task CalculateOxygenationIndex(BasePatientObservation obs)
    {
        var toSearchList = new List<string>();
@@ -655,6 +678,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The single-dose treatment whose end time is to be calculated.</param>
    /// <returns>The same <see cref="PatientTreatment"/> instance with its <c>EndTime</c> updated.</returns>
+    /// <!-- aidoc:v1 sig=271263e body=4ddb3f4 -->
    private static PatientTreatment CalculateSingleDoseEndDate(PatientTreatment treatment)
    {
        /* Deprecated calc finish treatment date on shift end. Now every treatment single dose is last 8 Hours
@@ -690,6 +714,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The treatment whose medicines should be checked.</param>
    /// <returns>A task that represents the asynchronous check operation.</returns>
+    /// <!-- aidoc:v1 sig=26b9617 body=0b5d20b -->
    public async Task CheckTreatmentMedicines(PatientTreatment treatment)
    {
        //sI TIENE UNA NOTA CON NPT SON DE TIPO NUTRICIÓN PARENTERAL Y SUMAN 1
@@ -784,6 +809,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The treatment to inspect for NPT indicators, or <see langword="null"/>.</param>
    /// <returns>A task that resolves to a <see cref="Medicine"/> instance describing the parenteral nutrition, or an unnamed, untyped instance when no NPT notes are present.</returns>
+    /// <!-- aidoc:v1 sig=d078407 body=3e76d41 -->
    private static Task<Medicine> CalculateParentalNutritionMedicine(PatientTreatment? treatment)
    {
        List<string> medicineType = [];
@@ -818,6 +844,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="medicines">The medicines to add or remove depending on <c>OrderControl</c>.</param>
    /// <param name="treatment">The treatment that triggered the recalculation.</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=0ed4852 body=363a6db -->
    public async Task CalculateMedicineObservation(List<Medicine> activeMedicines, List<Medicine> medicines,
        PatientTreatment treatment)
    {
@@ -876,6 +903,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="activeMedicines">The list of active medicines used to derive the risk level.</param>
    /// <param name="treatment">The treatment that triggered the recalculation.</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=b13c549 body=24f69f5 -->
    private async Task CalculateErMedication(List<Medicine> activeMedicines, PatientTreatment treatment)
    {
        //var activeTreatments = treatmentService.Value.GetActiveTreatmentsByPatient(treatment.patientid);
@@ -908,6 +936,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="activeMedicines">The list of active medicines to evaluate.</param>
    /// <returns>A task that resolves to the integer risk level (0–5).</returns>
+    /// <!-- aidoc:v1 sig=3c6a3b1 body=606ffd9 -->
    private static Task<int> CalculateErMedicineLevels(List<Medicine> activeMedicines)
    {
        var ironVitaminDCodes = new List<string> { "374424002", "175041000140104" };
@@ -964,6 +993,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The respiratory-mode observation expected to be a <see cref="PatientObservation"/>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=a32f888 body=5994877 -->
    public async Task CalculateVentilationMode(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -998,6 +1028,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (expected to be a <see cref="PatientObservation"/>).</param>
    /// <returns>A task that resolves to the same base patient observation that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=dbb815a body=5ae4249 -->
    public async Task<BasePatientObservation> CalculateAsistResp(BasePatientObservation obs)
    {
        //Comprobar si hay un resp_type más nuevo y si no lo hay ignorar
@@ -1057,6 +1088,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The treatment whose ECMO state is being applied.</param>
    /// <returns>A task that represents the asynchronous recalculation operation.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Documentation states 'In every case the change is followed by a complexity recalculation via CalculateComplexity', but the default case returns early without calling CalculateComplexity." -->
    private async Task CalculateComplexityOnEcmo(PatientTreatment treatment)
    {
        var ecmoObs = new PatientObservation
@@ -1102,6 +1135,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The base patient observation that triggered the recalculation.</param>
    /// <param name="ignoreObs">When <see langword="true"/>, the supplied <paramref name="obs"/> is not added to the calculation inputs (useful for synthetic observations like ECMO).</param>
    /// <returns>A task that resolves to the same base patient observation that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=b7809c7 body=cf3438b -->
    public async Task<BasePatientObservation> CalculateComplexity(BasePatientObservation obs, bool ignoreObs = false)
    {
        try
@@ -1278,6 +1312,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// early because the incoming observation is a duplicate insert (in which case the caller should
    /// not overwrite the stored observation).
    /// </returns>
+    /// <!-- aidoc:v1 sig=09f61b3 body=4d3947c -->
    public async Task<BasePatientObservation?> CalculateIntravenousLineObservation(BasePatientObservation obs)
    {
        try
@@ -1413,6 +1448,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation whose value represents the patient's weight.</param>
    /// <returns>A task that resolves to the integer complexity contribution (0–7).</returns>
+    /// <!-- aidoc:v1 sig=a79c349 body=4c9b390 -->
    private async Task<int> CalculateWeight(BasePatientObservation obs)
    {
        var complexityValueOfWeight = 0;
@@ -1445,6 +1481,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation expected to be a <see cref="PatientObservation"/> with a numeric value.</param>
    /// <returns>A task that resolves to the (possibly converted) base patient observation.</returns>
+    /// <!-- aidoc:v1 sig=18ad5f6 body=5d01118 -->
    public Task<BasePatientObservation> ParseWeight(BasePatientObservation obs)
    {
        if (obs is not PatientObservation pobs || !double.TryParse(pobs.Value.ToString(), out var dValue))
@@ -1471,6 +1508,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// derived from whichever type is supplied.
    /// </param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=9488dd5 body=f704b41 -->
    public async Task CalculateMonitor(object monitorObservation)
    {
        var monitorValue = 0;
@@ -1545,6 +1583,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The treatment that triggered the recalculation.</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=a3bb931 body=d219f09 -->
    private async Task CalculateSurgery(PatientTreatment treatment)
    {
        var surgeryScore = 0;
@@ -1596,6 +1635,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="patientId">The unique identifier of the patient.</param>
    /// <param name="newTreatment">The optional new treatment to be included in the active-bolus set.</param>
    /// <returns>A task that resolves to the list of treatments currently counted as active boluses.</returns>
+    /// <!-- aidoc:v1 sig=401adb8 body=c80c23f -->
    private async Task<List<PatientTreatment>> GetActiveBolus(ObjectId patientId, PatientTreatment? newTreatment)
    {
        var treatmentsProcessed = new List<PatientTreatment>();
@@ -1660,6 +1700,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The treatment that triggered the recalculation and should be included in the active-bolus set.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=493996c body=3ef85e3 -->
    private async Task CalculateBolus(PatientTreatment treatment)
    {
        var activeBolus = await GetActiveBolus(treatment.PatientId, treatment);
@@ -1686,6 +1727,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the alert evaluation (<c>TAm</c>, <c>Age_Gestational</c>, or <c>Age_Gestational_Fixed</c>).</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=857f5e0 body=0bf2cd4 -->
    public async Task CalculateTAmAlert(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -1749,6 +1791,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (<c>Temp_Patient</c> or <c>Temp_Incubator</c>).</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc:v1 sig=f3ac5ae body=4120ebf -->
    public async Task CalculateTempGradient(BasePatientObservation obs)
    {
        List<PatientObservation> tempRetrievedesFromBd;
@@ -14,6 +14,7 @@ namespace adas_core.Application.Customizations.HGM;
 /// <summary>
 /// Represents a collection of calculated observations, providing a concrete implementation of the <see cref="ICalculatedObservations"/> contract.
 /// </summary>
+/// <!-- aidoc:v1 sig=1b16cfc -->
 public class CalculatedObservations : ICalculatedObservations
 {
    private readonly List<string> _highFrequencyVentilation = [];
@@ -51,6 +52,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation to be mapped.</param>
    /// <param name="onlyByName">Flag indicating whether the mapping should be restricted to name-based criteria.</param>
    /// <returns>The mapped patient observation, or the original observation if no applicable mapping is found.</returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=stale_summary
+    ///      "The onlyByName parameter is documented as a 'Flag indicating whether the mapping should be restricted to name-based criteria,' but the parameter is never used in the method body. The switch statement processes cases based on name regardless of this flag." -->
    public async Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        if (string.IsNullOrEmpty(obs.Name)) return obs;
@@ -72,6 +75,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="treatment">The <see cref="PatientTreatment"/> instance to be mapped.</param>
    /// <returns>A task that represents the asynchronous mapping operation, containing the resulting <see cref="PatientTreatment"/>.</returns>
    /// <exception cref="System.NotImplementedException">Thrown to indicate that the method has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=adce250 body=bfa6f2f -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        throw new NotImplementedException();
@@ -83,6 +87,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="diagnosis">The patient diagnosis to be mapped.</param>
    /// <returns>A task that represents the asynchronous mapping operation, containing the mapped <see cref="PatientDiagnosis"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown when the method is invoked, as the mapping logic has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=8ddf601 body=bfa6f2f -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        throw new NotImplementedException();
@@ -93,6 +98,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A completed task containing the provided <see cref="PumpObservation"/>.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -104,6 +110,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient for whom the active bolus is calculated.</param>
    /// <exception cref="NotImplementedException">The method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=7d38721 body=bfa6f2f -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -115,6 +122,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="activeMedicines">The list of active medicines currently associated with the patient.</param>
    /// <param name="patientId">The unique identifier of the patient for whom the observation is being calculated.</param>
    /// <exception cref="NotImplementedException">The method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=b7a50a4 body=bfa6f2f -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -126,6 +134,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="newObservation">The new patient observation to reconcile against the last recorded observation.</param>
    /// <returns>A task that returns the corrected <see cref="PatientObservation"/>, or <c>null</c> when no last observation is available to compare against.</returns>
    /// <exception cref="System.NotImplementedException">The method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=cb71754 body=bfa6f2f -->
    public Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        throw new NotImplementedException();
@@ -137,6 +146,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="id">The identifier of the patient whose active treatments are being requested.</param>
    /// <returns>A task that yields a collection of active <see cref="PatientTreatment"/> entries for the patient.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=db74f82 body=bfa6f2f -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        throw new NotImplementedException();
@@ -147,6 +157,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to be pre-mapped.</param>
    /// <returns>A completed task containing the provided list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -158,6 +169,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation to return as the mapped result.</param>
    /// <param name="alarmToInsert">The patient observation alarm to be considered during mapping.</param>
    /// <returns>A <see cref="Task{PatientObservation}"/> containing the provided <paramref name="obs"/>.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -171,6 +183,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="code">The optional alarm code identifying the alarm type.</param>
    /// <returns>A task that represents the asynchronous alarm sending operation.</returns>
    /// <exception cref="NotImplementedException">Thrown when the method is invoked, as it is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -180,6 +193,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calculates and persists the ventilation mode (<c>Resp_Type</c>) for a patient observation by mapping the observed value against known high-frequency, invasive, and non-invasive ventilation vocabularies, defaulting to <c>None</c> when the value is empty or unrecognized.
    /// </summary>
    /// <param name="obs">The base patient observation whose value is used to derive the respiration type; it is cast to <see cref="PatientObservation"/> to access the value.</param>
+    /// <!-- aidoc:v1 sig=dd5b490 body=f8d6b73 -->
    private async Task CalculateVentilationMode(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -17,6 +17,7 @@ namespace adas_core.Application.Customizations.HPAZ;
 /// <remarks>
 /// This class implements the <see cref="ICalculatedObservations"/> contract, exposing the behavior defined by that interface while relying on constructor-injected services for its operations.
 /// </remarks>
+/// <!-- aidoc:v1 sig=c3598e8 -->
 public class CalculatedObservations(IServiceProvider serviceProvider) : ICalculatedObservations
 {
    private readonly Lazy<IAlarmService> _alarmService = serviceProvider.GetRequiredService<Lazy<IAlarmService>>();
@@ -42,6 +43,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// Asynchronously calculates the active bolus for the specified patient.
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient whose active bolus is to be calculated.</param>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary states the method 'calculates the active bolus', but the body only returns Task.CompletedTask without performing any calculation." -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -52,6 +55,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="activeMedicines">The list of medicines currently active for the patient.</param>
    /// <param name="patientId">The unique identifier of the patient whose medicine observations are being calculated.</param>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary states the method calculates medicine observations based on active medicines, but the body only returns Task.CompletedTask and performs no calculation." -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -63,6 +68,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="id">The unique identifier of the patient whose active treatments are being retrieved.</param>
    /// <returns>A task that represents the asynchronous operation, containing a collection of active <see cref="PatientTreatment"/> records for the patient, or an empty collection if none exist.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary states the method 'Retrieves the active treatments associated with the specified patient identifier,' but the implementation unconditionally returns an empty collection without performing any retrieval or checking the id parameter." -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        return Task.FromResult<IEnumerable<PatientTreatment?>>(new List<PatientTreatment?>());
@@ -75,6 +82,10 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="source">Observation</param>
    /// <param name="onlyByName">True if the observation needs to generate an alert</param>
    /// <returns>Mapped observation</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=mentions_removed_behavior
+    ///      "Summary states 'inserts it if needed', but the method body contains no insertion logic — it only maps/processes the observation and returns it." -->
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_param_role
+    ///      "onlyByName is documented as 'True if the observation needs to generate an alert', but the in-code comment states 'No generamos alertas si viene onlyByName' (alerts are NOT generated when onlyByName is true), and the parameter is never actually used in the method body." -->
    public async Task<T?> Map<T>(T source, bool onlyByName) where T : BasePatientObservation
    {
        _logger.LogDebug("Mapping {obsName} mode observation {obs}", source.Name, source);
@@ -113,6 +124,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pumpObservation">The source <see cref="PumpObservation"/> to map.</param>
    /// <returns>A task that represents the asynchronous mapping operation. The task result contains the mapped <see cref="PumpObservation"/>.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary states the method maps to a 'new PumpObservation instance', but the code returns the same pumpObservation instance unchanged." -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        try
@@ -212,6 +225,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="treatment">The <see cref="PatientTreatment"/> to be mapped.</param>
    /// <returns>A task representing the asynchronous operation, containing the mapped <see cref="PatientTreatment"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown in all cases because the method has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=adce250 body=bfa6f2f -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        throw new NotImplementedException();
@@ -223,6 +237,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="diagnosis">The <see cref="PatientDiagnosis"/> to be mapped.</param>
    /// <returns>A task that represents the asynchronous operation, containing the mapped <see cref="PatientDiagnosis"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown to indicate that the mapping logic has not been implemented.</exception>
+    /// <!-- aidoc:v1 sig=8ddf601 body=bfa6f2f -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        throw new NotImplementedException();
@@ -234,6 +249,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="newObservation">The new patient observation to validate and potentially adjust for time consistency.</param>
    /// <returns>The patient observation with its time corrected if a time inconsistency was detected, otherwise the original observation.</returns>
+    /// <!-- aidoc:v1 sig=2b42b30 body=3a31920 -->
    public async Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        if (string.IsNullOrEmpty(newObservation.Name))
@@ -267,6 +283,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="listToMap">The list of patient observations to process for mapping and blue code calculation.</param>
    /// <returns>The original list of patient observations passed to the method.</returns>
+    /// <!-- aidoc:v1 sig=655d2ec body=afe534e -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToMap)
    {
        var mappedObsList = listToMap
@@ -290,6 +307,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The target <see cref="PatientObservation"/> instance that will be updated with values from the alarm.</param>
    /// <param name="alarmToInsert">The source <see cref="PatientObservationAlarm"/> whose values are applied to <paramref name="obs"/>.</param>
    /// <returns>A completed <see cref="Task{PatientObservation}"/> containing the updated <paramref name="obs"/>.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=9a22777 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        if (!string.IsNullOrEmpty(alarmToInsert.EventId))
@@ -310,6 +328,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="name">The name of the alarm to be sent.</param>
    /// <param name="code">The optional alarm code identifying the type of alarm.</param>
    /// <exception cref="System.NotImplementedException">Thrown because the method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=9d68c3e body=bfa6f2f -->
    Task ICalculatedObservations.SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -323,6 +342,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="name">The name of the alarm.</param>
    /// <param name="code">The optional alarm code identifier.</param>
    /// <param name="type">The type of alarm to send.</param>
+    /// <!-- aidoc:v1 sig=cd9926e body=38786f6 -->
    private async Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code, AlarmEnum.Type type)
    {
        await _alarmService.Value.SendAlarm(obs, name, code, AlarmEnum.Severity.None, type);
@@ -334,6 +354,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="obs">Observation</param>
    /// <returns>True if it needs to be ignored</returns>
+    /// <!-- aidoc:v1 sig=9343b34 body=bfb9ed9 -->
    private bool CheckIfObservationIsOlderAndShouldBeIgnored(PatientObservation obs)
    {
        if (obs.Time.ToUniversalTime().AddMinutes(_apiSettings.IgnoreCalcObservationsOlderInMinutesThan) <
@@ -354,6 +375,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pobs">The patient observation whose alarm configuration should be resolved; its <c>Name</c> and <c>PatientId</c> are used to locate the configuration.</param>
    /// <returns>The same <see cref="PatientObservation"/> instance with its <c>Alarm</c> property populated from the matching configuration, or <c>null</c> when no configuration is found.</returns>
+    /// <!-- aidoc:v1 sig=4d79a28 body=efca777 -->
    private async Task<PatientObservation> CheckAlarmConfig(PatientObservation pobs)
    {
        var configObs = await _configObservationService.Get(new PatientObservation
@@ -373,6 +395,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="name">The alarm code used to identify the type of alarm; it is set as the <c>Code</c> and used to compose the <c>Name</c>.</param>
    /// <param name="pobs">The source patient observation whose value, patient identifier, time, and alarm flag are copied into the new alarm observation.</param>
    /// <returns>A new <see cref="PatientObservation"/> configured as an ADAS alarm observation based on the provided source.</returns>
+    /// <!-- aidoc:v1 sig=235b1d9 body=27fc0a4 -->
    private static PatientObservation CreateAlarmObservation(string name, PatientObservation pobs)
    {
        return new PatientObservation
@@ -391,6 +414,10 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    ///     Checks if a blue code observation Lists needs to be generated and inserts it.
    /// </summary>
    /// <param name="obsList"></param>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The method does not 'generate' or 'insert' a blue code observation list; it evaluates clinical conditions (FC, SpO2, TAm) and calls SendBlueCode to trigger a notification. The summary misrepresents both the action and the outcome." -->
+    /// <!-- aidoc-review:v1 severity=high kind=missing_param
+    ///      "The <param name='obsList'> tag has no description." -->
    public async Task CalculateBlueCodeList(List<PatientObservation?>? obsList)
    {
        //Las 3 observaciones vienen siempre juntas en el mismo mensaje
@@ -461,6 +488,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// Sends a Blue Code alarm for the given patient observation. If the observation is null, the method returns without taking any action; otherwise it creates the corresponding alarm observation, validates it against the alarm configuration, persists it, and dispatches the alarm as an automatically triggered Blue alarm.
    /// </summary>
    /// <param name="pobs">The patient observation that triggers the Blue Code alarm; when null, the method short-circuits without processing.</param>
+    /// <!-- aidoc:v1 sig=5b6ce3f body=c8aa765 -->
    private async Task SendBlueCode(PatientObservation? pobs)
    {
        if (pobs == null)
@@ -486,6 +514,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="obs">The base patient observation value whose ventilation mode will be calculated and normalized.</param>
    /// <returns>The patient observation with the normalized ventilation mode value.</returns>
+    /// <!-- aidoc:v1 sig=0a38ecd body=8d45d84 -->
    private BasePatientObservationValue CalculateVentilationMode(BasePatientObservationValue obs)
    {
        var value = obs is PatientObservationAlarm oAlarm ? oAlarm.Value
@@ -508,6 +537,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="obs">The patient observation to evaluate; non-<see cref="PatientObservation"/> instances are returned unchanged.</param>
    /// <returns>The original observation, with its <c>Time</c> adjusted by one second when a matching observation is found.</returns>
+    /// <!-- aidoc:v1 sig=a546fa4 body=b8e5fa3 -->
    private async Task<BasePatientObservationValue> CheckObsWithSameTimeExistsAndIncrementTime(
            BasePatientObservationValue obs)
    {
@@ -529,6 +559,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="obs">The newly received patient observation that triggered the calculation; its Name must be either "FiO2" or "Sattc".</param>
    /// <param name="name">The name of the observation, used to determine whether <paramref name="obs"/> is the FiO2 or the Sattc value.</param>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_summary
+    ///      "The summary states the calculation is 'logged and skipped' when the insertion conditions are not met, but only the FiO2 == 0 case triggers a log message; other skip conditions (expired observations, unparseable values, null complementary observation, sat > 97) silently skip without logging." -->
    private async Task CalculateSf(BasePatientObservationValue obs, string name)
    {
        try
@@ -590,6 +622,8 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    ///     calculation if they are not
    ///     in database then  does nothing.
    /// </summary>
+    /// <!-- aidoc-review:v1 severity=medium kind=missing_param
+    ///      "The parameters 'obs' (BasePatientObservationValue containing the triggering observation) and 'name' (the name of the observation being processed, used to switch on which value was provided) are not documented." -->
    public async Task CalculateOxygenationIndex(BasePatientObservationValue obs, string name)
    {
        var toSearchList = new List<string>();
@@ -665,6 +699,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="obs">The current patient observation that initiated the calculation; provides the patient identifier and timestamp used for the resulting observation.</param>
    /// <param name="name">The name of the observation in <paramref name="obs"/>, expected to be either <c>FiO2</c> or <c>PaO2_Tidal</c>, which determines how the counterpart value is resolved.</param>
+    /// <!-- aidoc:v1 sig=1b41d79 body=5e03ddd -->
    private async Task CalculatePf(BasePatientObservationValue obs, string name)
    {
        try
@@ -729,6 +764,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="name">The alarm identifier used to build the observation <c>Code</c> and <c>Name</c>.</param>
    /// <param name="pumpObservation">The pump data source providing rack/auxiliary info, drug name, time, and optional patient id.</param>
    /// <returns>A <see cref="Task{PatientObservation}"/> that yields the resulting observation, or <c>null</c> when the alarm configuration check rejects it.</returns>
+    /// <!-- aidoc:v1 sig=adcd93c body=8ef1fe1 -->
    private async Task<PatientObservation?> CreatePumpAlarmObservation(string name,
            PumpObservation pumpObservation)
    {
@@ -18,6 +18,7 @@ namespace adas_core.Application.Customizations.HRYC;
 /// Resp_Type, and Hour_Balance) from incoming raw observations and active configurations loaded from
 /// <see cref="ApiSettings"/>.
 /// </summary>
+/// <!-- aidoc:v1 sig=1b16cfc -->
 public class CalculatedObservations : ICalculatedObservations
 {
    private readonly IOptions<ApiSettings> _apiSettings;
@@ -42,6 +43,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// from <see cref="ApiSettings"/>.
    /// </summary>
    /// <param name="serviceProvider">The application's service provider used to resolve the required dependencies and configuration.</param>
+    /// <!-- aidoc:v1 sig=409f903 body=cf624d7 -->
    public CalculatedObservations(IServiceProvider serviceProvider)
    {
        _observationService = serviceProvider.GetRequiredService<Lazy<IObservationService>>(); //observationService;
@@ -86,6 +88,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// A <see cref="Task{T}"/> that resolves to the (possibly transformed) observation,
    /// or <see langword="null"/> when the input observation has no name.
    /// </returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_returns
+    ///      "Documentation claims the method returns null 'when the input observation has no name', but the method always returns the (possibly transformed) obs parameter; the code never returns null, so the null branch described in <returns> does not exist." -->
    public async Task<T?> Map<T>(T obs, bool onlyByName) where T : BasePatientObservation
    {
        _logger.LogTrace("Mapping {name} observation {obs}", obs.Name, obs);
@@ -148,6 +152,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="treatment">The treatment to map.</param>
    /// <returns>Never returns a result.</returns>
    /// <exception cref="NotImplementedException">Always thrown because treatment mapping is not implemented in the HRYC customization.</exception>
+    /// <!-- aidoc:v1 sig=adce250 body=bfa6f2f -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        throw new NotImplementedException();
@@ -161,6 +166,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A task containing the same <see cref="PumpObservation"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -174,6 +180,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="activeMedicines">The list of active medicines (ignored).</param>
    /// <param name="patientId">The unique identifier of the patient (ignored).</param>
    /// <returns>A completed task.</returns>
+    /// <!-- aidoc:v1 sig=b7a50a4 body=6805ef5 -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -185,6 +192,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient (ignored).</param>
    /// <returns>A completed task.</returns>
+    /// <!-- aidoc:v1 sig=7d38721 body=6805ef5 -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        return Task.CompletedTask;
@@ -196,6 +204,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="id">The unique identifier of the patient (ignored).</param>
    /// <returns>A completed task containing an empty <see cref="IEnumerable{PatientTreatment}"/>.</returns>
+    /// <!-- aidoc-review:v1 severity=low kind=wrong_returns
+    ///      "The cref references IEnumerable{PatientTreatment}, but the actual return type is IEnumerable{PatientTreatment?} (element type is nullable)." -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        return Task.FromResult(new List<PatientTreatment?>().AsEnumerable());
@@ -207,6 +217,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="diagnosis">The <see cref="PatientDiagnosis"/> to map.</param>
    /// <returns>A task containing the same <see cref="PatientDiagnosis"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=8ddf601 body=ad326e6 -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        return Task.FromResult(diagnosis);
@@ -224,6 +235,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// A task that resolves to the (possibly time-shifted) <see cref="PatientObservation"/>.
    /// Returns the input unchanged when its <c>Name</c> is null or empty, logging the error.
    /// </returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_summary
+    ///      "Summary states the time is shifted 'when it arrives with the same (down-to-the-second) timestamp' as the latest observation, but the code actually shifts whenever the last observation's second-truncated time is greater than OR equal to the new observation's (DateTime.Compare >= 0), i.e., it also corrects cases where the new observation arrives earlier than the latest one." -->
    public async Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        if (string.IsNullOrEmpty(newObservation.Name))
@@ -262,6 +275,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// A task that resolves to the resulting list of observations (with <c>Vent_Rate</c> removed
    /// when it was inserted synchronously, or the original list otherwise).
    /// </returns>
+    /// <!-- aidoc:v1 sig=e508c09 body=d3232c6 -->
    public async Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        var ventRate = listToInsert.FirstOrDefault(obs => obs.Name == "MDC_VENT_RESP_RATE");
@@ -312,6 +326,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation that triggered the alarm.</param>
    /// <param name="alarmToInsert">The alarm metadata to be inserted alongside the observation.</param>
    /// <returns>A task containing the same <see cref="PatientObservation"/> instance that was passed in.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -327,6 +342,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="code">The optional alarm code from <see cref="AlarmEnum.Name"/>.</param>
    /// <returns>Never returns a result.</returns>
    /// <exception cref="NotImplementedException">Always thrown because this overload is not used in the HRYC customization.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -339,6 +355,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> whose <c>Name</c> is <c>NEWS</c>.</param>
    /// <returns>A task that represents the asynchronous alarm evaluation.</returns>
+    /// <!-- aidoc:v1 sig=a2f90ec body=b1f8d11 -->
    private async Task CalculateNews(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -382,6 +399,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The base patient observation that triggered the alarm (used to derive <c>PatientId</c> and <c>Time</c>).</param>
    /// <param name="name">The <see cref="AlarmEnum.Name"/> describing the alarm kind (for example, <c>NewsOff</c>, <c>NewsWarning</c>, <c>NewsAlert</c>).</param>
    /// <returns>A task that represents the asynchronous alarm dispatch.</returns>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "Summary states 'The alarm observation is always persisted', but the method returns early without calling InsertObservation when configObs is null (and also when an exception is thrown), so persistence is not guaranteed." -->
    private async Task SendAlarm(BasePatientObservation obs, AlarmEnum.Name name)
    {
        var pobs = (PatientObservation)obs;
@@ -444,6 +463,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="color">The beacon colour to apply.</param>
    /// <param name="patient">The patient whose associated beacon should be updated.</param>
+    /// <!-- aidoc:v1 sig=aced090 body=6297307 -->
    private void SendBeaconCode(AlarmEnum.BeaconColor color, Patient patient)
    {
        if (!patient.PointOfCareId.HasValue)
@@ -478,6 +498,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (<c>SpO2</c>, <c>FiO2</c>, or <c>FR</c>).</param>
    /// <returns>A task that represents the asynchronous calculation operation.</returns>
+    /// <!-- aidoc-review:v1 severity=low kind=stale_summary
+    ///      "Documentation states observations must be 'within the last 10 minutes', but the code checks `o.Time.CompareTo(DateTime.UtcNow.AddMinutes(10)) <= 0` (10 minutes in the future), which is a much more permissive check that allows any past observation and does not enforce a 10-minute-ago cutoff." -->
    private async Task CalculateIrox(BasePatientObservation obs)
    {
        try
@@ -560,6 +582,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (<c>FR</c> or <c>Vent_Rate</c>).</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=0c7e3f7 body=e68f279 -->
    private async Task CalculateRespRate(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -627,6 +650,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Hydric_Balance</c>.</param>
    /// <returns>A task that resolves to the (possibly time-shifted) base patient observation.</returns>
+    /// <!-- aidoc:v1 sig=443610d body=4a73250 -->
    private async Task<BasePatientObservation> CalculateHydricBalance(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -650,6 +674,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Hour_Balance</c>.</param>
    /// <returns>A task that resolves to the (possibly time-shifted) base patient observation.</returns>
+    /// <!-- aidoc:v1 sig=23cf188 body=8e46c30 -->
    private async Task<BasePatientObservation> CalculateHourBalance(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -677,6 +702,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Hydric_Balance</c>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=721b70b body=271caec -->
    private async Task CalculateHydricBalanceCalculated(BasePatientObservation obs)
    {
        //Hydric_Balance_Calculated 
@@ -753,6 +779,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Resp_Mode</c>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc-review:v1 severity=low kind=stale_summary
+    ///      "Summary references identifier 'InvasiveVentilation' (in <c> tags) but the actual field is '_codesForInvasiveVentilation'." -->
    private async Task CalculateVentilationMode(BasePatientObservation obs)
    {
        _logger.LogDebug("CalculateVentilationMode {obs}", obs);
@@ -800,6 +828,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Weight_Current</c>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=cb420e5 body=6df7b22 -->
    private async Task CalculateWeight_DiffObservation(BasePatientObservation obs)
    {
        var toSearchList = new List<string>();
@@ -839,6 +868,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (<c>Diuresis</c> or <c>Weight_Current</c>).</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=c96d1b4 body=0dfe456 -->
    private async Task CalculateDiureis_WeightObservation(BasePatientObservation obs)
    {
        var toSearchList = new List<string>();
@@ -891,6 +921,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>AllergiesObs</c> and a collection-valued <c>Value</c> of <see cref="PatientAllergiesValue"/>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=16bb26b body=661f911 -->
    private async Task CalculateAllergiesObservation(BasePatientObservation obs)
    {
        try
@@ -967,6 +998,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>DrainagesObs</c> and a <see cref="PatientDrainagesValue"/>-typed <c>Value</c>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=2e0f71d body=98b8c9e -->
    private async Task CalculateDrainagesObservation(BasePatientObservation obs)
    {
        var pobs = (PatientObservation)obs;
@@ -1013,6 +1045,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation (<c>PEEP</c> or <c>Pleateu_Pressure</c>).</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=fe22b05 body=bc944b3 -->
    private async Task CalculateDelta_PressureObservation(BasePatientObservation obs)
    {
        var toSearchList = new List<string>();
@@ -1071,6 +1104,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation, expected to be a <see cref="PatientObservation"/> with <c>Name</c> <c>Daily_Balance</c>.</param>
    /// <returns>A task that represents the asynchronous insert operation.</returns>
+    /// <!-- aidoc:v1 sig=e959764 body=2322c22 -->
    private async Task CalculateDaily_BalanceObservation(BasePatientObservation obs)
    {
        if (obs.Time.ToLocalTime().Hour == 8)
@@ -1098,6 +1132,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <see langword="true"/> when the observation has an <c>Expires</c> value and the current time
    /// is past the expiration instant; otherwise, <see langword="false"/>.
    /// </returns>
+    /// <!-- aidoc:v1 sig=c7c5c82 body=4c62b98 -->
    private static bool CheckExpired(PatientObservation obs)
    {
        if (obs.Expires == null) return false;
@@ -15,6 +15,7 @@ namespace adas_core.Application.Customizations.HUVH.UCIA;
 /// Represents a concrete implementation of the <see cref="ICalculatedObservations"/> interface,
 /// providing functionality to manage a collection of calculated observations.
 /// </summary>
+/// <!-- aidoc:v1 sig=1b16cfc -->
 public class CalculatedObservations : ICalculatedObservations
 {
    private const string CodingSystem = "ADAS";
@@ -67,6 +68,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The identifier of the patient whose active bolus should be calculated.</param>
    /// <exception cref="NotImplementedException">Thrown when the method is invoked, as the calculation logic has not yet been implemented.</exception>
+    /// <!-- aidoc-review:v1 severity=medium kind=stale_summary
+    ///      "The summary states that the method 'calculates the active bolus', but the body only throws NotImplementedException and performs no calculation; the <exception> tag mitigates this by noting the logic is not yet implemented." -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -79,6 +82,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation to map; may be replaced with the result of the matched asynchronous calculation when applicable.</param>
    /// <param name="onlyByName">Indicates whether the mapping should be performed using only the observation's name.</param>
    /// <returns>The processed patient observation, potentially updated by the applicable calculation.</returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=mentions_removed_behavior
+    ///      "The <param name=\"onlyByName\"> describes behavior ('Indicates whether the mapping should be performed using only the observation's name'), but the parameter is never referenced anywhere in the method body; the dispatching always relies solely on the observation's name regardless of this flag." -->
    public async Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        if (obs.Name is "PSI" or "RASS" or "TS") _ = CalculateOverSedation(obs);
@@ -106,6 +111,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment to map and update.</param>
    /// <returns>The patient treatment with its order control set according to the evaluated business rules.</returns>
+    /// <!-- aidoc:v1 sig=442a6e8 body=e1bed22 -->
    public async Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        var order = treatment.PlacerOrder?.EntityIdentifier; //aquí almacenamos el número de orden
@@ -130,6 +136,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A completed task containing the provided <see cref="PumpObservation"/>.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -141,6 +148,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="activeMedicines">The list of currently active medicines assigned to the patient.</param>
    /// <param name="patientId">The unique identifier of the patient whose medication categories will be checked.</param>
+    /// <!-- aidoc-review:v1 severity=high kind=wrong_summary
+    ///      "The summary claims the method 'calculates medicine observations', but the implementation only invokes CheckMedicationCategories and returns Task.CompletedTask; no observation calculation is performed." -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        //Esto viene del schedulerService para chequear los medicamentos activos
@@ -154,6 +163,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="id">The unique identifier of the patient whose active treatments should be retrieved.</param>
    /// <returns>A collection of <see cref="PatientTreatment"/> objects representing the patient's active treatments.</returns>
+    /// <!-- aidoc:v1 sig=1c9e799 body=2a62eb7 -->
    public async Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        var activeTreatments = await _treatmentService.Value.GetActiveTreatmentsByPatient(id);
@@ -167,6 +177,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="diagnosis">The <see cref="PatientDiagnosis"/> to be mapped.</param>
    /// <returns>A task that represents the asynchronous mapping operation, containing the resulting <see cref="PatientDiagnosis"/>.</returns>
    /// <exception cref="NotImplementedException">Thrown when the method is invoked, as the mapping logic has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=8ddf601 body=bfa6f2f -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        throw new NotImplementedException();
@@ -179,6 +190,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="newObservation">The new patient observation whose timestamp should be adjusted to avoid time inconsistencies with prior observations.</param>
    /// <returns>The patient observation, with its <c>Time</c> adjusted when a time collision is detected, or the original observation when its name is null or empty.</returns>
+    /// <!-- aidoc:v1 sig=2b42b30 body=04118be -->
    public async Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        if (string.IsNullOrEmpty(newObservation.Name))
@@ -211,6 +223,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to pre-map before insertion.</param>
    /// <returns>A completed task containing the provided list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -222,6 +235,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation to be returned as the mapping result.</param>
    /// <param name="alarmToInsert">The patient observation alarm intended to be associated with the observation.</param>
    /// <returns>A task containing the patient observation.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -235,6 +249,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="code">The optional alarm code categorizing the alarm, or null if no code is specified.</param>
    /// <returns>A task that represents the asynchronous alarm sending operation.</returns>
    /// <exception cref="NotImplementedException">Thrown to indicate that the method has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -246,6 +261,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation to evaluate for the rehabilitation alarm condition.</param>
    /// <returns>The observation with its status set to Alert when the six previous rehabilitation observations also fall within the 0-2 range; otherwise the observation is returned as-is.</returns>
+    /// <!-- aidoc:v1 sig=4d51d03 body=02faf98 -->
    private async Task<BasePatientObservation> CalculateRehabilitationAlarm(BasePatientObservation obs)
    {
        //En rojo si el grado es de 0 a 2 incluidos, por más de 7 días
@@ -270,6 +286,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The incoming base patient observation; only <see cref="PatientObservation"/> instances whose
    /// <c>Name</c> is "Diuresis" or "Weight" are processed, otherwise the method returns without changes.</param>
+    /// <!-- aidoc:v1 sig=a9e1f01 body=35f930e -->
    private async Task CalculateDiuresis(BasePatientObservation obs)
    {
        // Calculado como el sumatorio de la Diuresis de las últimas 6h 
@@ -350,6 +367,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calculates the ROX Index by dividing the SpO2/FiO2 ratio by the respiratory rate (FR) and persists the result as a new <c>Rox_Index</c> observation. The method supports both directions of the calculation: when the incoming observation is the SpO2/FiO2 ratio, it retrieves the latest FR, and vice versa. It silently returns if the observation is not a <c>PatientObservation</c>, if the observation name is not recognized, if the required paired observation cannot be found, if its value cannot be parsed, or if the FR value is zero (to avoid division by zero).
    /// </summary>
    /// <param name="obs">The base patient observation that triggers the ROX index calculation. Only observations named <c>SpO2_FiO2_Ratio</c> or <c>FR</c> are processed; any other type or name is ignored.</param>
+    /// <!-- aidoc:v1 sig=b303a48 body=1e098ad -->
    private async Task CalculateRoxIndex(BasePatientObservation obs)
    {
        // Cálculo dividiendo el ratio SpO2/FiO2 entre la FR
@@ -402,6 +420,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calculates the driving pressure for a patient as the difference between Pmeset and PEEP when a new Pmeset or PEEP observation is provided. Looks up the complementary observation to obtain the missing value, then creates and persists a "Driving_Pressure" observation. Returns early if the input is not a PatientObservation, the observation name is neither Pmeset nor PEEP, the complementary observation cannot be found, or its value cannot be parsed as an integer.
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation; expected to represent a Pmeset or PEEP measurement.</param>
+    /// <!-- aidoc:v1 sig=b3a7d66 body=19b29eb -->
    private async Task CalculateDrivingPressure(BasePatientObservation obs)
    {
        //Diferencia entre la Pmeset y la PEEP
@@ -458,6 +477,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The observation that triggered the evaluation; its value must be numeric and it is ignored if <paramref name="patientId"/> is provided (e.g., when invoked from a treatment context).</param>
    /// <param name="patientId">The patient identifier when the evaluation is triggered by a treatment event; when null, it is derived from <paramref name="obs"/>.</param>
+    /// <!-- aidoc:v1 sig=28b0d06 body=65c1f9b -->
    private async Task CalculateOverAnalgesia(BasePatientObservation? obs, ObjectId? patientId = null)
    {
        // Mandar observación 'SOBREANALGESIA'
@@ -537,6 +557,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation to evaluate and potentially transform.</param>
    /// <returns>A task that yields the observation, with its value normalized to "ECMO" when the original value is one of the recognized ECMO variants.</returns>
+    /// <!-- aidoc:v1 sig=5673ebb body=65604a9 -->
    private Task<BasePatientObservation> CalculateEcmoLocation(BasePatientObservation obs)
    {
        //Las opciones pueden ser VV, VA o ECMO.
@@ -564,6 +585,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// anything.
    /// </summary>
    /// <param name="obs">The incoming patient observation whose name drives the ventilation mode calculation.</param>
+    /// <!-- aidoc:v1 sig=dd5b490 body=76605b5 -->
    private async Task CalculateVentilationMode(BasePatientObservation obs)
    {
        //- Si llega valor de PI pero NO COMPL, el tipo de ventilación es VMNI
@@ -619,6 +641,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The triggering patient observation used to evaluate the sedation state. When provided, its name and value drive the initial validation; when null, the method relies on the <paramref name="patientId"/> parameter (typically from a treatment update).</param>
    /// <param name="patientId">Optional identifier of the patient to evaluate. If null, it is derived from <paramref name="obs"/>; otherwise, the method performs a full evaluation using the patient's recent observations.</param>
+    /// <!-- aidoc:v1 sig=0a9014e body=8a7e50f -->
    private async Task CalculateOverSedation(BasePatientObservation? obs, ObjectId? patientId = null)
    {
        //Mandar observación 'SOBRESEDACIÓN'
@@ -700,6 +723,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment to evaluate; may be null.</param>
    /// <returns><c>true</c> if the treatment has a start time and was started more than 24 hours ago; otherwise, <c>false</c>.</returns>
+    /// <!-- aidoc:v1 sig=ee619c2 body=c94e0d4 -->
    private static bool ExceedsAnalgesiaThreshold(PatientTreatment? treatment)
    {
        // Perfusiones de morfina, remifentanilo o fentanilo sostenidas > 24 h
@@ -713,6 +737,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment to evaluate, or <c>null</c>.</param>
    /// <returns><c>true</c> if the treatment is not <c>null</c> and any requested medication exceeds its defined sedation threshold; otherwise, <c>false</c>.</returns>
+    /// <!-- aidoc:v1 sig=5aa55d0 body=d2a9955 -->
    private static bool ExceedsSedationThreshold(PatientTreatment? treatment)
    {
        return (treatment != null &&
@@ -729,6 +754,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment whose patient is used to look up the list of active treatments to evaluate.</param>
    /// <returns>A task that returns the list of active patient treatments that were not discontinued.</returns>
+    /// <!-- aidoc:v1 sig=4f3a796 body=a702644 -->
    private async Task<List<PatientTreatment>> CheckExpiredPatientTreatments(PatientTreatment treatment)
    {
        //si el tratamiento ha expirado actualizamos el OrderControl a DC y devolvemos las que siguen activas
@@ -757,6 +783,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// further validation.
    /// </summary>
    /// <param name="treatment">The patient treatment whose requested medicines will be checked against the patient's active medicines.</param>
+    /// <!-- aidoc:v1 sig=e762e81 body=63b9252 -->
    private async Task CheckTreatmentMedicines(PatientTreatment treatment)
    {
        var newMedicines = (await Task.WhenAll(treatment.RequestedGiveCodes
@@ -785,6 +812,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The identifier of the patient whose medication categories are being evaluated and linked to the created observations.</param>
    /// <param name="uniqueMedicines">The distinct list of medicines to be checked against the predefined category reference lists.</param>
+    /// <!-- aidoc:v1 sig=ef6fae4 body=be6580c -->
    private void CheckMedicationCategories(ObjectId patientId, List<Medicine> uniqueMedicines)
    {
        var medicationCategories = new Dictionary<string, List<string>?>
@@ -821,6 +849,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="medications">The collection of medications whose names will be stored as the observation values.</param>
    /// <param name="patientId">The identifier of the patient the observation belongs to.</param>
    /// <param name="obsName">The name used to group and look up the previous observation for the same concept.</param>
+    /// <!-- aidoc:v1 sig=c1a952c body=987bc59 -->
    private async Task CreateMedicationMultivalueObservation(IEnumerable<Medicine?> medications, ObjectId patientId,
            string obsName)
    {
@@ -16,6 +16,7 @@ namespace adas_core.Application.Customizations.HUVH.UCIN;
 /// Represents a concrete implementation of the <see cref="ICalculatedObservations"/> interface,
 /// providing a collection of calculated observation data.
 /// </summary>
+/// <!-- aidoc:v1 sig=1b16cfc -->
 public class CalculatedObservations : ICalculatedObservations
 {
    private const string Spo2PreObservationName = "SpO2";
@@ -61,6 +62,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient for whom the active bolus is calculated.</param>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=7d38721 body=bfa6f2f -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -73,6 +75,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation to be mapped, which may be transformed depending on its name.</param>
    /// <param name="onlyByName">Indicates whether the mapping should be performed using only the observation name.</param>
    /// <returns>The mapped patient observation, potentially enriched with computed values, wrapped in a task.</returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_param_role
+    ///      "The 'onlyByName' parameter is documented as controlling whether 'the mapping should be performed using only the observation name,' but the parameter is never referenced in the method body, so passing a value for it has no effect on the mapping behavior." -->
    public async Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        if (obs.Name is "Intervention_In" or "Intervention_Out") await CalculateInterventionMultiValueObservation(obs);
@@ -105,6 +109,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment to map, including its placer order, end time, and medicines.</param>
    /// <returns>The mapped <see cref="PatientTreatment"/> with its order control type and medicines updated.</returns>
+    /// <!-- aidoc:v1 sig=442a6e8 body=e1bed22 -->
    public async Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        var order = treatment.PlacerOrder?.EntityIdentifier; //aquí almacenamos el número de orden
@@ -129,6 +134,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="pumpObservation">The pump observation to map.</param>
    /// <returns>A completed <see cref="Task{TResult}"/> containing the provided <see cref="PumpObservation"/>.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -140,6 +146,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="activeMedicines">The list of active medicines from which distinct medication names are extracted to build the observation value.</param>
    /// <param name="patientId">The identifier of the patient for whom the medication observation is calculated and stored.</param>
+    /// <!-- aidoc:v1 sig=299c0fe body=8145436 -->
    public async Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        var medicineObs = new PatientObservation
@@ -171,6 +178,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="id">The unique <see cref="ObjectId"/> of the patient whose active treatments should be fetched.</param>
    /// <returns>A task that represents the asynchronous operation, containing an <see cref="IEnumerable{T}"/> of nullable <see cref="PatientTreatment"/> instances for the patient.</returns>
+    /// <!-- aidoc:v1 sig=1c9e799 body=2a62eb7 -->
    public async Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        var activeTreatments = await _treatmentService.Value.GetActiveTreatmentsByPatient(id);
@@ -184,6 +192,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="diagnosis">The source <see cref="PatientDiagnosis"/> instance to be mapped.</param>
    /// <returns>A <see cref="Task{PatientDiagnosis}"/> that represents the asynchronous mapping operation, containing the mapped <see cref="PatientDiagnosis"/>.</returns>
    /// <exception cref="T:System.NotImplementedException">Thrown when the method is invoked, as the mapping logic has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=8ddf601 body=bfa6f2f -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        throw new NotImplementedException();
@@ -195,6 +204,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="newObservation">The new patient observation whose time may be adjusted to follow the most recent observation for the same patient and measurement.</param>
    /// <returns>The patient observation with a corrected time if a time conflict was detected, or the original observation if no adjustment was needed or the name was invalid.</returns>
+    /// <!-- aidoc:v1 sig=2b42b30 body=04118be -->
    public async Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        if (string.IsNullOrEmpty(newObservation.Name))
@@ -227,6 +237,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to pre-map.</param>
    /// <returns>A task that represents the asynchronous operation, containing the provided list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);
@@ -238,6 +249,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="obs">The patient observation that the alarm is to be associated with.</param>
    /// <param name="alarmToInsert">The alarm intended to be inserted into the observation.</param>
    /// <returns>A task containing the patient observation, returned as-is.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -250,6 +262,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="name">The name associated with the alarm.</param>
    /// <param name="code">The optional alarm code categorizing the type of alarm to be sent.</param>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented.</exception>
+    /// <!-- aidoc:v1 sig=90426a4 body=bfa6f2f -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        throw new NotImplementedException();
@@ -261,6 +274,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Returns without creating a record when the observation is not a <see cref="PatientObservation"/> or when its name does not match any of the supported scales.
    /// </summary>
    /// <param name="obs">The source patient observation used to derive the pain scale; only instances of <see cref="PatientObservation"/> with a supported name (ALPS, NPASS_Sedation, NPASS_Analgesia) are processed.</param>
+    /// <!-- aidoc:v1 sig=f89cebc body=f5dfb0c -->
    private async Task CalculatePainScale(BasePatientObservation obs)
    {
        if (obs is not PatientObservation pobs) return;
@@ -314,6 +328,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The base patient observation to process.</param>
    /// <returns>The original <see cref="BasePatientObservation"/> if it is not a <see cref="PatientObservation"/>; otherwise, the <see cref="PatientObservation"/> with its value set to the locally formatted observation time.</returns>
+    /// <!-- aidoc:v1 sig=479318b body=e536a62 -->
    private static BasePatientObservation CalculateLastDefecationValue(BasePatientObservation obs)
    {
        if (obs is not PatientObservation pobs) return obs;
@@ -332,6 +347,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calculates and persists a multi-value observation by appending the current value to the existing list of values for the corresponding "Multivalue" observation. Expirates the previous multi-value observation before inserting the new one.
    /// </summary>
    /// <param name="obs">The base patient observation used to derive the multi-value observation; it must be a <see cref="PatientObservation"/> with a non-empty name and a string value.</param>
+    /// <!-- aidoc:v1 sig=d821a40 body=264c069 -->
    private async Task CalculateMultiValueObservation(BasePatientObservation obs)
    {
        //El valor de la observación es un array de strings
@@ -388,6 +404,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calculates and persists a multi-value observation that aggregates the active intervention groups (e.g., devices, routes) for a patient based on incoming "<c>_In</c>" and "<c>_Out</c>" observations. Handles the insertion of new groups (with special duplicate prevention for respiratory devices) and the removal of groups when a corresponding "Out" event is received, expiring the previous multi-value observation and inserting a new one when the resulting set is not empty.
    /// </summary>
    /// <param name="obs">The base patient observation that triggered the calculation; expected to be a <see cref="PatientObservation"/> with a non-empty name and a string value representing the intervention group.</param>
+    /// <!-- aidoc:v1 sig=25ac55d body=191bd88 -->
    private async Task CalculateInterventionMultiValueObservation(BasePatientObservation obs)
    {
        if (obs is not PatientObservation pobs || string.IsNullOrEmpty(obs.Name) ||
@@ -478,6 +495,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="valueObs">Observation text from which the leading token is taken as the candidate intervention code.</param>
    /// <param name="r">When the method returns true, contains the resolved intervention's type, name, and group; otherwise null.</param>
    /// <returns><c>true</c> if a matching intervention was found; <c>false</c> if the code is not numeric or the lookup yields no result.</returns>
+    /// <!-- aidoc:v1 sig=d3884cf body=1ea9ac7 -->
    private bool GetInterventionValue(string valueObs, out (string type, string Name, string Group)? r)
    {
        var code = valueObs.Split(" ")[0]; //
@@ -506,6 +524,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// Calcula la complejidad del paciente en función de las observaciones registradas.
    /// </summary>
    /// <param name="obs">Observación del paciente que se va a evaluar para recalcular su complejidad.</param>
+    /// <!-- aidoc:v1 sig=4545d3a body=a6e9e71 -->
    private async Task CalculateComplexity(BasePatientObservation obs)
    {
        var pobs = obs as PatientObservation;
@@ -575,6 +594,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="observationName">The name of the multivalue observation to look up and calculate complexity for.</param>
    /// <param name="observation">An optional pre-loaded observation that overrides the database lookup when supplied.</param>
    /// <returns>The aggregated complexity value for the observation, or 0 if no observation or values are found.</returns>
+    /// <!-- aidoc:v1 sig=cdba6ba body=3c7e7fd -->
    private async Task<int> CalculateMultivalueObservationComplexityValue(ObjectId patientId, string observationName,
            PatientObservation? observation = null)
    {
@@ -602,6 +622,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// <param name="patientId">The identifier of the patient whose newborn weight complexity is being calculated.</param>
    /// <param name="pobs">An optional patient observation to use instead of the latest stored one; if provided with "kg" units, its value is converted.</param>
    /// <returns>The calculated newborn weight complexity value, or 0 when no valid value is available.</returns>
+    /// <!-- aidoc:v1 sig=85b6f46 body=c89d98c -->
    private async Task<int> CalculateWeightNewBornValue(ObjectId patientId, PatientObservation? pobs = null)
    {
        var result =
@@ -644,6 +665,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The patient observation containing the weight value to parse and convert.</param>
    /// <returns>The patient observation with the value converted to grams, or the original observation if the value could not be parsed.</returns>
+    /// <!-- aidoc:v1 sig=2d84953 body=d947a19 -->
    private PatientObservation ParseWeight(PatientObservation obs)
    {
        if (!double.TryParse(obs.Value.ToString(), out var dValue))
@@ -664,6 +686,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="obs">The incoming patient observation (either a pre or post SpO2 measurement) used to drive the calculation and identify the counterpart observation.</param>
    /// <returns>A task that represents the asynchronous insert of the derived observations.</returns>
+    /// <!-- aidoc:v1 sig=7f9be58 body=e3f6858 -->
    private async Task CalculateSaturation_DiffObservation(BasePatientObservation obs)
    {
        var toSearchList = new List<string>();
@@ -726,6 +749,8 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="treatment">The patient treatment being evaluated, used to locate the existing record by its placer order entity identifier and to persist the updated state.</param>
    /// <returns>A task that yields the list of active patient treatments for the patient that are not the same placer order as the supplied treatment.</returns>
+    /// <!-- aidoc-review:v1 severity=medium kind=wrong_summary
+    ///      "Summary claims to 'check for expired patient treatments' but the code calls GetActiveTreatmentsByPatient (active, not expired) and sets DC when t.EndTime > DateTime.UtcNow (future, not past), making the word 'expired' contradictory to the documented condition 'end time is in the future'." -->
    private async Task<List<PatientTreatment>> CheckExpiredPatientTreatments(PatientTreatment treatment)
    {
        //si el tratamiento ha expirado actualizamos el OrderControl a DC y devolvemos las que siguen activas
@@ -763,6 +788,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// medicines remain after filtering.
    /// </summary>
    /// <param name="treatment">The patient treatment whose requested give codes are inspected for medicines, nutrition items, and vasoactive drugs.</param>
+    /// <!-- aidoc:v1 sig=e762e81 body=6f65d8e -->
    private async Task CheckTreatmentMedicines(PatientTreatment treatment)
    {
        var newMedicines = new List<Medicine>();
@@ -825,6 +851,7 @@ public class CalculatedObservations : ICalculatedObservations
    /// </summary>
    /// <param name="value">The feeding type value to record; if it contains "parenteral" (case-insensitive), the observation is stored as a parenteral entry.</param>
    /// <param name="patientId">The identifier of the patient to whom the observation belongs.</param>
+    /// <!-- aidoc:v1 sig=7b17fa3 body=af49d06 -->
    private async Task CreateNutritionObservation(string value, ObjectId patientId)
    {
        var nutritionObs = new PatientObservation
@@ -10,6 +10,7 @@ namespace adas_core.Application.Customizations.NursePlan;
 /// <summary>
 /// Provides calculated observations by leveraging services obtained from the injected service provider.
 /// </summary>
+/// <!-- aidoc:v1 sig=c3598e8 -->
 public class CalculatedObservations(IServiceProvider serviceProvider) : ICalculatedObservations
 {
    private readonly Lazy<IObservationService> _observationService =
@@ -20,6 +21,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="patientId">The unique identifier of the patient whose active bolus is to be calculated.</param>
    /// <exception cref="System.NotImplementedException">Thrown when the method is invoked, as the calculation logic has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=7d38721 body=bfa6f2f -->
    public Task CalculateActiveBolus(ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -30,6 +32,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="pumpObservation">The PumpObservation to be mapped.</param>
    /// <returns>A task containing the mapped PumpObservation.</returns>
+    /// <!-- aidoc:v1 sig=50be4c1 body=e481734 -->
    public async Task<PumpObservation> Map(PumpObservation pumpObservation)
    {
        return await Task.FromResult(pumpObservation);
@@ -42,6 +45,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="activeMedicines">The collection of medicines currently active for the patient.</param>
    /// <param name="patientId">The identifier of the patient whose medicine observation is being calculated.</param>
    /// <exception cref="NotImplementedException">The method is not yet implemented.</exception>
+    /// <!-- aidoc:v1 sig=b7a50a4 body=bfa6f2f -->
    public Task CalculateMedicineObservation(List<Medicine> activeMedicines, ObjectId patientId)
    {
        throw new NotImplementedException();
@@ -53,6 +57,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="newObservation">The new patient observation whose timestamps may need to be reconciled with the last recorded observation.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the fixed <see cref="PatientObservation"/>, or <c>null</c> when no time inconsistency is detected.</returns>
    /// <exception cref="NotImplementedException">Thrown because the method has not been implemented yet.</exception>
+    /// <!-- aidoc:v1 sig=cb71754 body=bfa6f2f -->
    public Task<PatientObservation?> FixTimeInconsistencyWithLast(PatientObservation newObservation)
    {
        throw new NotImplementedException();
@@ -64,6 +69,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="id">The unique identifier of the patient whose active treatments are being queried.</param>
    /// <returns>A task representing the asynchronous operation, containing a collection of active PatientTreatment entries, which may include null values, for the specified patient.</returns>
    /// <exception cref="NotImplementedException">The method has not yet been implemented.</exception>
+    /// <!-- aidoc:v1 sig=db74f82 body=bfa6f2f -->
    public Task<IEnumerable<PatientTreatment?>> GetActiveTreatmentsByPatient(ObjectId id)
    {
        throw new NotImplementedException();
@@ -75,6 +81,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation to return.</param>
    /// <param name="onlyByName">Reserved flag that is not used in the current implementation.</param>
    /// <returns>A completed task containing the provided observation.</returns>
+    /// <!-- aidoc:v1 sig=21d06c4 body=9f66f26 -->
    public Task<T?> Map<T>(T obs, bool onlyByName = false) where T : BasePatientObservation
    {
        return Task.FromResult(obs)!;
@@ -85,6 +92,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="treatment">The patient treatment to map.</param>
    /// <returns>A task containing the mapped patient treatment.</returns>
+    /// <!-- aidoc:v1 sig=adce250 body=cf46cd2 -->
    public Task<PatientTreatment> Map(PatientTreatment treatment)
    {
        return Task.FromResult(treatment);
@@ -95,6 +103,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="diagnosis">The patient diagnosis to be returned as a completed task result.</param>
    /// <returns>A completed <see cref="Task{PatientDiagnosis}"/> containing the provided diagnosis.</returns>
+    /// <!-- aidoc:v1 sig=8ddf601 body=ad326e6 -->
    public Task<PatientDiagnosis> Map(PatientDiagnosis diagnosis)
    {
        return Task.FromResult(diagnosis);
@@ -107,6 +116,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation to return.</param>
    /// <param name="alarmToInsert">The patient observation alarm; not used in the current implementation.</param>
    /// <returns>A completed task containing the original <paramref name="obs"/>.</returns>
+    /// <!-- aidoc:v1 sig=405db8e body=ea790e4 -->
    public Task<PatientObservation> MapSourceAlarm(PatientObservation obs, PatientObservationAlarm alarmToInsert)
    {
        return Task.FromResult(obs);
@@ -118,6 +128,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// <param name="obs">The patient observation that triggers the alarm.</param>
    /// <param name="name">The name associated with the alarm.</param>
    /// <param name="code">The optional alarm code identifying the alarm type.</param>
+    /// <!-- aidoc:v1 sig=90426a4 body=6805ef5 -->
    public Task SendAlarm(PatientObservation obs, string name, AlarmEnum.Name? code)
    {
        return Task.CompletedTask;
@@ -128,6 +139,7 @@ public class CalculatedObservations(IServiceProvider serviceProvider) : ICalcula
    /// </summary>
    /// <param name="listToInsert">The list of patient observations to be pre-mapped.</param>
    /// <returns>A completed <see cref="Task{TResult}"/> containing the original list of patient observations.</returns>
+    /// <!-- aidoc:v1 sig=5a37e9b body=0791af0 -->
    public Task<List<PatientObservation>> PreMapList(List<PatientObservation> listToInsert)
    {
        return Task.FromResult(listToInsert);