docs: close source comment remediation

docs/audits/documentation_inventory.md

@@ -619,6 +619,7 @@ Translation of historical evidence must preserve the historical checkpoint exact
 - DOCUMENTATION_INVENTORY_AUDIT=PASS_WITH_FINDINGS
 - DOCUMENTATION_FINDING_REMEDIATION=PASS
 - DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS
-- SOURCE_COMMENT_AUDIT=NEXT
-- PRODUCT_DEFINITION=NOT_STARTED
+- SOURCE_COMMENT_AUDIT=PASS
+- SOURCE_COMMENT_REMEDIATION=PASS
+- PRODUCT_DEFINITION=NEXT
 - PROMPT_TREE=NOT_STARTED

docs/audits/source_comment_inventory.md

@@ -0,0 +1,99 @@
+# Lardon3D — Source Comment Audit
+
+## Status
+
+```text
+SOURCE_COMMENT_AUDIT=PASS
+SOURCE_COMMENT_REMEDIATION=PASS
+SOURCE_COMMENT_SCOPE=include/lardon3d/** + src/**
+SOURCE_COMMENT_LANGUAGE=ENGLISH
+SOURCE_CODE_BEHAVIOR_CHANGED=NO
+```
+
+The audit covered 148 C/C++ source/header files under `include/lardon3d/**` and `src/**`.
+
+The initial static inventory reported:
+
+```text
+comment blocks                         807
+raw non-English lexical candidates     33
+actual French comment blocks            29
+English false positives                  4
+stale-contract candidates                0
+raw unannotated-public declarations    324
+```
+
+## Remediation
+
+All 29 actual French source comments were translated to English.
+
+The four raw language-detector false positives were already English and were left unchanged.
+
+The remediation touched comments only. A file-level lexical comparison removed comments entirely and verified that every non-comment source
+byte remained identical before and after the declared replacements.
+
+No executable UI/error string was changed in this pass. UI language is a separate explicitly scoped
+implementation pass.
+
+## Stale and misleading comments
+
+The lexical stale-contract pass found zero candidate comments.
+
+No scientific threshold, schema version, Task Kind, resource contract, persistence identity or FROZEN
+boundary was changed by this audit.
+
+## Public API adjacency heuristic
+
+The first inventory reported 324 public declarations without an immediately adjacent comment.
+
+That number is **informational only**, not 324 defects.
+
+The repository Source Comment Contract requires comments where WHY, CONTRACT, INVARIANT, OWNERSHIP,
+IDENTITY, persistence ordering, restart, cancellation, concurrency, resource accounting or a FROZEN
+boundary is non-obvious. It does not require one redundant comment for every getter, thin wrapper,
+paired create/load/list function or declaration already covered by a surrounding contract block.
+
+Therefore absence of an adjacent comment alone is not a valid
+`UNDER_COMMENTED`/`SEVERELY_UNDER_COMMENTED` finding.
+
+Future audits must review semantic contract coverage rather than using declaration adjacency as a
+blanket failure criterion.
+
+## Source Comment Contract
+
+Production source comments:
+
+- are English;
+- explain non-obvious WHY/CONTRACT/INVARIANT facts;
+- preserve ownership and lifetime boundaries;
+- preserve persistence/restart ordering;
+- preserve concurrency/resource-accounting boundaries;
+- preserve scientific identity and FROZEN constraints;
+- do not paraphrase obvious code line-by-line;
+- are updated when behavior changes.
+
+## Validation
+
+The remediation runner requires:
+
+```text
+branch = docs-audit
+no unrelated worktree changes
+all expected old comments match exactly once
+file-level source with all comments removed remains byte-for-byte identical
+no strong French-comment candidate remains
+git diff --check passes
+```
+
+## Phase state
+
+```text
+DOCUMENTATION_FINDING_REMEDIATION=PASS
+DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS
+
+SOURCE_COMMENT_AUDIT=PASS
+SOURCE_COMMENT_REMEDIATION=PASS
+
+PRODUCT_DEFINITION=NEXT
+PROMPT_TREE=NOT_STARTED
+```

include/lardon3d/candidate_pair_gen.h

@@ -9,9 +9,9 @@
 #include <lardon3d/visual_index.h>
 
 typedef struct {
-  uint32_t generated_count;    // paires nouvellement créées
-  uint32_t skipped_count;      // paires déjà existantes (idempotence)
-  uint32_t queried_count;      // candidats retournés par le Visual Index
+  uint32_t generated_count;    // newly created pairs
+  uint32_t skipped_count;      // already existing pairs (idempotent reuse)
+  uint32_t queried_count;      // candidates returned by the Visual Index
 } Lardon3DCandidatePairGenStats;
 
 Lardon3DVisualIndexResult lardon3d_candidate_pair_generate(

include/lardon3d/import_task.h

@@ -42,7 +42,7 @@ bool lardon3d_project_enqueue_image_import(Lardon3DAppState *state, uint64_t sca
 bool lardon3d_image_import_reconstruct(const Lardon3DTaskDurableSnapshot *snapshot, void *context,
                                        Lardon3DTaskKindBinding *binding);
 
-/* Compatibilité TUI : handle léger sur une tâche de la queue, sans thread. */
+/* TUI compatibility: lightweight handle over a Queue Task, with no private thread. */
 Lardon3DImportTask *lardon3d_import_task_create(void);
 bool lardon3d_import_task_start(Lardon3DImportTask *task, Lardon3DAppState *state,
                                 const char *source_directory);

include/lardon3d/resource_governor.h

@@ -325,11 +325,11 @@ const char *lardon3d_resource_decision_name(
 Lardon3DResourcePressure lardon3d_resource_governor_pressure(
     Lardon3DResourceGovernor *governor
 );
-/* Enregistre les métriques d'un lot terminé pour l'adaptation dynamique
- * de la taille des lots futurs. batch_size est le nombre d'éléments dont le
- * traitement a été validé dans ce lot. peak_memory_bytes == 0 signifie que
- * la mesure est inconnue et n'alimente jamais l'adaptation mémoire. Le buffer
- * est borné (8 entrées par classe de tâche). Thread-safe. */
+/* Records metrics from one completed batch for dynamic adaptation of future
+ * batch sizes. batch_size is the number of items whose processing was validated
+ * in this batch. peak_memory_bytes == 0 means the measurement is unknown and
+ * never feeds memory adaptation. The buffer is bounded to 8 entries per Task
+ * class. Thread-safe. */
 bool lardon3d_resource_governor_record_batch(
     Lardon3DResourceGovernor *governor,
     Lardon3DResourceTaskClass task_class,

include/lardon3d/task.h

@@ -108,8 +108,8 @@ Lardon3DTask *lardon3d_task_create_typed(
     Lardon3DTaskUserdataDestroy userdata_destroy
 );
 void lardon3d_task_destroy(Lardon3DTask *task);
-/* Exécute le callback dans le thread appelant. Le callback est invoqué hors
- * mutex de tâche; le contract d'exécution et l'état appartiennent à la tâche.
+/* Executes the callback on the calling thread. The callback runs outside
+ * the Task mutex; the execution contract and state remain owned by the Task.
  */
 bool lardon3d_task_start(
     Lardon3DTask *task,
@@ -169,16 +169,16 @@ Lardon3DTask *lardon3d_task_restore_typed(
     void *userdata,
     Lardon3DTaskUserdataDestroy userdata_destroy
 );
-/* Une restauration typée réussie transfère userdata/userdata_destroy à la
- * tâche. En cas d'échec, l'appelant en reste propriétaire. */
+/* A successful typed restore transfers userdata/userdata_destroy ownership
+ * to the Task. On failure, the caller retains ownership. */
 bool lardon3d_task_kind_is_valid(const char *task_kind);
 bool lardon3d_task_kind(
     const Lardon3DTask *task,
     char task_kind[LARDON3D_TASK_KIND_CAPACITY],
     uint32_t *task_kind_version
 );
-/* Appelé au plus une fois, hors mutex de tâche et après libération de la
- * réservation terminale. Le userdata de tâche reste vivant jusqu'au retour. */
+/* Invoked at most once, outside the Task mutex and after the terminal
+ * reservation is released. Task userdata remains alive until the callback returns. */
 bool lardon3d_task_set_finished_callback(
     Lardon3DTask *task,
     Lardon3DTaskFinishedCallback callback,
@@ -190,21 +190,20 @@ bool lardon3d_task_resource_estimate(
     const Lardon3DTask *task,
     Lardon3DResourceEstimate *estimate
 );
-/* L'exécution ne reçoit pas de politique d'admission : c'est au gouverneur de
- * confirmer la réservation avant l'exécution.
+/* Execution does not receive admission policy: the Governor must confirm
+ * the reservation before execution.
  */
 bool lardon3d_task_execution_contract(
     const Lardon3DTask *task,
     Lardon3DTaskExecutionContract *contract
 );
-/* Libère la réservation courante, en obtient une nouvelle auprès du gouverneur
- * et met à jour le contrat. À appeler uniquement depuis le callback en cours
- * d'exécution. Une réponse WAIT du gouverneur est une indisponibilité
- * temporaire : la fonction attend un changement de ressources puis retente
- * l'admission sans échouer la tâche. Les bornes de lot se poursuivent après
- * cette nouvelle admission. Retourne false si la tâche est annulée
- * (TASK_CANCELLED), si le gouverneur répond REJECT ou en cas d'erreur interne
- * (TASK_FAILED). */
+/* Releases the current reservation, obtains a new one from the Governor,
+ * and updates the execution contract. Call only from the currently executing
+ * callback. A Governor WAIT is temporary unavailability: this function waits
+ * for a resource change and retries admission without failing the Task. Batch
+ * bounds continue under the new admission. Returns false if the Task is
+ * cancelled (TASK_CANCELLED), the Governor returns REJECT, or an internal
+ * error fails the Task (TASK_FAILED). */
 bool lardon3d_task_sequence_break(
     Lardon3DTask *task,
     Lardon3DResourceGovernor *governor,

include/lardon3d/task_queue.h

@@ -42,10 +42,6 @@ typedef struct {
  * serialized worker. capacity bounds pending Tasks, not terminal history; the
  * Governor retains resource-admission ownership and must outlive the Queue.
  *
- * File d'exécution bornée, à ordre d'attente FIFO avec sélection adaptative du
- * premier travail admissible, et un seul worker: ownership d'ordonnancement et
- * de backpressure seulement. L'admission des demandes reste au Governneur.
- *
  * CONTRACT: after a successful add, the Queue owns Task and its userdata. Once
  * the Task is terminal and its finished callback has returned, the Queue keeps
  * only a snapshot and promptly destroys the real Task outside the Queue lock.
@@ -73,8 +69,8 @@ Lardon3DTaskQueue *lardon3d_task_queue_create(
  * starts after destruction safe. NULL is accepted. Never call destroy
  * synchronously from a Task finished callback running on this Queue. */
 void lardon3d_task_queue_destroy(Lardon3DTaskQueue *queue);
-/* La file devient propriétaire de task uniquement en cas de succès.
- * Bloquante : attend une place libre si la file est pleine. A zero Task ID is
+/* The Queue takes ownership of task only on success.
+ * Blocking: waits for a free slot when the Queue is full. A zero Task ID is
  * assigned from a nonzero monotonic sequence and is never generated twice
  * during this Queue lifetime, including after terminal-history eviction or
  * removal. Once UINT64_MAX has been generated (or consumed by a restored
@@ -85,8 +81,8 @@ bool lardon3d_task_queue_add(
     Lardon3DTask *task,
     uint64_t *task_id
 );
-/* Non-bloquante : retourne false si la file est pleine ou en arrêt.
-   La file devient propriétaire de task uniquement en cas de succès. */
+/* Non-blocking: returns false if the Queue is full or stopping.
+   The Queue takes ownership of task only on success. */
 bool lardon3d_task_queue_try_add(
     Lardon3DTaskQueue *queue,
     Lardon3DTask *task,

src/acquisition_campaign_task.cpp

@@ -397,9 +397,9 @@ bool run_impl(Lardon3DTask *t, void *p) {
             c->db, lardon3d_task_id(t), group_id, materialized_capture_id,
             group_id) != LARDON3D_PROJECT_DB_OK)
       return lardon3d_task_fail(t, "Rétention de Capture impossible.");
-    /* Limite de reprise acceptée: entre le retour de S3-E et cette rétention
-     * durable, une identité de capture ne peut pas être déduite à posteriori
-     * depuis les chemins/métadonnées/ID d'image.
+    /* Accepted recovery boundary: between S3-E returning and this durable
+     * retention, Capture identity cannot be reconstructed retroactively from
+     * paths, metadata, or image IDs.
      */
 #ifdef LARDON3D_ACQUISITION_CAMPAIGN_TASK_TESTING
     const char *after_retention =

src/resource_governor.c

@@ -1797,8 +1797,8 @@ record_batch_locked(
     metrics[head] = (Lardon3DBatchMetrics) {
         .batch_size = batch_size,
         .duration_ns = duration_ns,
-        /* Zéro est le marqueur persistant « mesure inconnue ». La boucle
-         * d'adaptation ignore explicitement ces échantillons. */
+        /* Zero is the sentinel for an unknown measurement. The adaptation
+         * loop explicitly ignores these samples. */
         .peak_memory_bytes = peak_memory_bytes,
     };
     head = (head + 1) % LARDON3D_BATCH_METRICS_CAPACITY;
@@ -1836,9 +1836,9 @@ adaptive_batch_limit(
             % LARDON3D_BATCH_METRICS_CAPACITY;
         const Lardon3DBatchMetrics *m = &governor->batch_metrics[class_index][idx];
         if (m->batch_size > 0 && m->peak_memory_bytes > 0) {
-            /* Coût par élément le plus défavorable observé : une moyenne
-             * sous-estimerait le pic et laisserait un lot dépasser son
-             * budget. La stabilité de l'hôte prime sur le débit. */
+            /* Use the worst observed per-item cost: an average would
+             * underestimate the peak and could let a batch exceed its
+             * budget. Host safety takes precedence over throughput. */
             uint64_t per_item = m->peak_memory_bytes / m->batch_size
                 + (m->peak_memory_bytes % m->batch_size != 0);
             if (per_item > measured_per_item) {
@@ -1853,9 +1853,9 @@ adaptive_batch_limit(
     if (measured_per_item <= memory_bytes_per_item) {
         return static_batch;
     }
-    /* Éviter l'overflow de la multiplication : si static_batch est trop
-     * grand pour être multiplié sans débordement, on retourne 1 (le lot le
-     * plus conservateur possible) plutôt que de saturer à SIZE_MAX. */
+    /* Avoid multiplication overflow: if static_batch is too large to
+     * multiply safely, return 1 (the most conservative batch) instead of
+     * saturating to SIZE_MAX. */
     if (static_batch > UINT64_MAX / memory_bytes_per_item) {
         return 1;
     }
@@ -3222,10 +3222,10 @@ evaluate_locked(
             )
         );
     }
-    /* Le lot maximal visé est corrigé par les métriques mesurées : c'est la
-     * nouvelle cible du contrat, pas une réduction faute de ressources. La
-     * correction ne descend jamais sous minimum_batch_size pour éviter un
-     * WAIT persistant. */
+    /* Measured metrics adjust the target maximum batch: this becomes the
+     * contract target, not a reduction caused by current resource shortage.
+     * The adjustment never falls below minimum_batch_size, avoiding a
+     * persistent WAIT. */
     size_t adapted_maximum = adaptive_batch_limit(
         governor,
         estimate->task_class,
@@ -3626,7 +3626,7 @@ lardon3d_resource_governor_record_batch(
         return false;
     }
     if (batch_size == 0) {
-        /* No-op réussi : aucune métrique, aucun réveil inutile. */
+        /* Successful no-op: no metrics and no unnecessary wake-up. */
         return true;
     }
     (void)pthread_mutex_lock(&governor->mutex);

src/task.c

@@ -612,8 +612,8 @@ lardon3d_task_destroy(Lardon3DTask *task)
                 "Annulation demandée.");
             (void)pthread_cond_broadcast(&task->condition);
         } else {
-            /* Une tâche locale jamais soumise peut être abandonnée sans
-             * publier une fausse annulation métier. */
+            /* A local Task that was never submitted may be abandoned without
+             * publishing a false business-level cancellation. */
             finish_locked(task, TASK_CANCELLED, "Tâche abandonnée.");
             task->finished_notified = true;
         }
@@ -885,7 +885,7 @@ lardon3d_task_checkpoint(Lardon3DTask *task)
 }
 
 enum {
-    /* Attente bornée entre deux tentatives d'admission : 50 ms. */
+    /* Bounded wait between admission attempts: 50 ms. */
     LARDON3D_SEQUENCE_ADMISSION_WAIT_NS = 50000000ULL,
 };
 
@@ -931,7 +931,7 @@ lardon3d_task_sequence_break(
         (void)lardon3d_resource_governor_release(governor, previous);
     }
     for (;;) {
-        /* Vérifier pause et annulation avant chaque tentative d'admission. */
+        /* Check pause and cancellation before every admission attempt. */
         (void)pthread_mutex_lock(&task->mutex);
         while (task->pause_requested && !task->cancel_requested) {
             task->state = TASK_PAUSED;
@@ -962,7 +962,7 @@ lardon3d_task_sequence_break(
             &next
         );
         if (!admitted) {
-            /* Erreur interne : échec d'allocation ou d'instantané. */
+            /* Internal error: allocation or resource-snapshot failure. */
             if (next) {
                 (void)lardon3d_resource_governor_release(governor, next);
             }
@@ -1079,8 +1079,8 @@ lardon3d_task_sequence_break(
             (void)pthread_mutex_unlock(&task->mutex);
             return false;
         case LARDON3D_RESOURCE_WAIT:
-            /* Indisponibilité temporaire : ne pas échouer, attendre un
-             * changement de ressources puis retenter l'admission. */
+            /* Temporary unavailability: do not fail the Task; wait for a
+             * resource change and retry admission. */
             if (next) {
                 (void)lardon3d_resource_governor_release(governor, next);
             }
@@ -1091,7 +1091,7 @@ lardon3d_task_sequence_break(
             );
             break;
         default:
-            /* Décision inconnue : erreur interne, ne jamais boucler. */
+            /* Unknown decision: internal error; never loop on it. */
             if (next) {
                 (void)lardon3d_resource_governor_release(governor, next);
             }

src/task_queue.c

@@ -290,9 +290,9 @@ unlink_pending(Lardon3DTaskQueue *queue, TaskNode *previous, TaskNode *node)
     }
     node->next_pending = NULL;
     --queue->pending_count;
-    /* Chaque retrait libère une place. Plusieurs producteurs peuvent dormir
-     * pendant que le worker retire plusieurs tâches avant qu'ils reprennent
-     * le mutex ; chacun de ces retraits doit donc produire un réveil. */
+    /* Every removal frees one slot. Multiple producers may be asleep while
+     * the worker removes several Tasks before they reacquire the mutex, so
+     * every removal must signal one waiter. */
     (void)pthread_cond_signal(&queue->not_full);
 }
 
@@ -361,12 +361,11 @@ destroy_retired(TaskNode *retired)
     }
 }
 
-/* Parcourt la file d'attente dans son ordre FIFO et sélectionne la première
- * tâche admissible; une attente de ressources peut donc laisser passer une
- * tâche antérieure sans lui faire perdre sa place dans la file.
- * Les tâches terminales ou refusées sont retirées de la file d'attente.
- * Une tâche en attente de ressources reste en file et sera réévaluée.
- * Retourne NULL si aucune tâche ne peut démarrer immédiatement. */
+/* Scans pending Tasks in FIFO order and selects the first admissible one.
+ * A resource WAIT may therefore let a later Task run without removing the
+ * waiting Task from its position. Terminal or rejected Tasks are removed.
+ * A resource-waiting Task remains queued for later re-evaluation.
+ * Returns NULL when no Task can start immediately. */
 static TaskNode *
 select_admissible(
     Lardon3DTaskQueue *queue,
@@ -541,10 +540,10 @@ queue_worker(void *context)
                 );
             }
         }
-        /* La tâche peut avoir libéré et re-réservé via sequence_break pendant
-         * son callback. Dans ce cas la réservation d'origine est déjà libérée
-         * et cet appel est sans effet ; la réservation courante de la tâche a
-         * été libérée par lardon3d_task_start. */
+        /* The Task may have released and re-reserved through sequence_break
+         * during its callback. In that case the original reservation is
+         * already released and this call is a no-op; lardon3d_task_start
+         * released the Task's current reservation. */
         if (reservation) {
             (void)lardon3d_resource_governor_release(
                 queue->governor,
@@ -763,7 +762,7 @@ lardon3d_task_queue_destroy(Lardon3DTaskQueue *queue)
     free(queue);
 }
 
-/* Appelée sous le mutex queue. Ne signale pas not_empty sur échec. */
+/* Called with the Queue mutex held. Does not signal not_empty on failure. */
 static bool
 enqueue_locked(
     Lardon3DTaskQueue *queue,