# Flusso KNN Shadow — progetto s190js

## Panoramica

Il confronto KNN in modalità **shadow** viene eseguito lato **server Node.js**, non nel browser. Il flusso parte dal worker che aggiorna i prototipi facciali e arriva al binario nativo `face_knn`, passando attraverso il modulo di confronto, il runtime KNN e uno script shell.

```text
Server Node.js
└── tools/runPrototypeWorker.js
    └── tools/runFaceKnnShadow.js
        └── tools/faceKnnRuntime.js
            └── native/face-knn/run-face-knn.sh
                └── native/face-knn/bin/face_knn
```

Percorso del progetto usato negli esempi:

```bash
/home/nvme/dockerdata/prove/s190js
```

## Ruolo dei componenti

### 1. `tools/runPrototypeWorker.js` — worker Node.js

È il processo server che gestisce i job di aggiornamento dei prototipi facciali.

In sintesi:

1. recupera un job in stato `pending`;
2. lo porta in elaborazione (`processing`);
3. esegue la procedura principale di selezione dei prototipi;
4. salva il risultato nel database;
5. dopo il salvataggio, avvia il confronto KNN shadow.

Il confronto shadow viene quindi eseguito **dopo** il salvataggio del risultato principale. Non è il componente che decide quali prototipi selezionare nella procedura ordinaria.

### 2. `tools/runFaceKnnShadow.js` — confronto KNN in modalità shadow

Questo modulo coordina il confronto tra i risultati KNN nativi e quelli di riferimento prodotti dall'esperimento.

Il suo compito è verificare e registrare eventuali differenze. In modalità `shadow`, il risultato del KNN nativo è usato per validazione e analisi: non sostituisce la selezione principale dei prototipi.

Eventuali errori o discrepanze del confronto vengono registrati nei log; secondo il flusso esaminato, non annullano il salvataggio dei prototipi già completato.

### 3. `tools/faceKnnRuntime.js` — runtime KNN

Questo modulo prepara e avvia l'esecuzione del KNN nativo.

In base al codice esaminato, si occupa di attività come:

- leggere la configurazione KNN;
- recuperare gli embedding delle facce e i prototipi da confrontare;
- preparare i file di input temporanei richiesti dal programma nativo;
- invocare il launcher configurato;
- leggere e interpretare l'output JSON del binario.

Il launcher è configurato nel file:

```text
native/face-knn/config.json
```

Il valore atteso per `launcher` è:

```text
native/face-knn/run-face-knn.sh
```

L'effettiva esecuzione dipende dalla configurazione: il KNN deve essere abilitato e la modalità shadow deve essere attiva.

### 4. `native/face-knn/run-face-knn.sh` — script shell

È il punto di ingresso shell usato per lanciare il programma nativo.

Lo script cambia nella propria directory e poi esegue il binario:

```text
./bin/face_knn
```

Questo passaggio permette al programma nativo di trovare correttamente i file relativi alla propria directory, come il kernel OpenCL, senza dipendere dalla directory da cui è stato avviato il server.

Lo script è quindi un **launcher lato server**. Non viene eseguito dal browser.

### 5. `native/face-knn/bin/face_knn` — binario nativo

È il programma compilato che esegue il confronto KNN.

Riceve dal runtime i percorsi dei file di input e i parametri necessari, come il numero di query, il numero di prototipi, la dimensione degli embedding, il valore di `top-k` e il backend richiesto.

Il programma restituisce i risultati al processo Node.js, che li interpreta e li usa nel rapporto di confronto shadow.

## Quando viene eseguito il flusso

Il flusso non viene eseguito semplicemente perché un utente apre una pagina web.

Viene avviato dal worker server durante l'elaborazione di un job di aggiornamento dei prototipi, dopo il completamento del salvataggio principale, se la configurazione KNN abilita il confronto shadow.

L'assegnazione di un cluster a una persona accoda un job di aggiornamento dei prototipi. Il daemon/worker elabora quel job; il confronto KNN shadow è una fase successiva del lavoro server.

## Cosa fa e cosa non fa la modalità shadow

| Attività | Componente principale |
|---|---|
| Gestire il job di aggiornamento | `runPrototypeWorker.js` |
| Selezionare e salvare i prototipi principali | Worker e procedura di selezione |
| Coordinare il confronto di validazione | `runFaceKnnShadow.js` |
| Preparare input e invocare il programma nativo | `faceKnnRuntime.js` |
| Avviare il binario | `run-face-knn.sh` |
| Eseguire il calcolo KNN nativo | `bin/face_knn` |

**Importante:** in modalità `shadow`, il KNN nativo è un controllo parallelo di validazione. Non è il motore che determina direttamente quali prototipi vengono salvati. Per cambiare questo comportamento servirebbe una modifica esplicita al flusso applicativo e una verifica separata.

## Verifiche sul server

Per controllare la configurazione effettiva e i punti di collegamento, eseguire sul server:

```bash
cd /home/nvme/dockerdata/prove/s190js

echo "=== Configurazione KNN ==="
cat native/face-knn/config.json

echo
echo "=== Collegamenti nel codice ==="
grep -n -E \
  'runFaceKnnShadow|runNativeKnn|launcher|spawnSync' \
  tools/runPrototypeWorker.js \
  tools/runFaceKnnShadow.js \
  tools/faceKnnRuntime.js
```

Per verificare che lo script shell lanci il binario previsto:

```bash
cd /home/nvme/dockerdata/prove/s190js

cat native/face-knn/run-face-knn.sh
ls -l native/face-knn/run-face-knn.sh \
      native/face-knn/bin/face_knn
```

## Nota sul fallback

La configurazione può contenere un backend di fallback, ad esempio CPU. La sola presenza di un'impostazione come `fallbackBackend` non dimostra però che il codice esegua automaticamente un secondo tentativo in caso di errore. Per affermarlo con certezza occorre verificare nel runtime il percorso di gestione degli errori e l'eventuale seconda invocazione.

## Conclusione

La catena è interamente lato server:

```text
runPrototypeWorker.js
    → runFaceKnnShadow.js
        → faceKnnRuntime.js
            → run-face-knn.sh
                → bin/face_knn
```

Il worker principale salva i prototipi; successivamente, se la configurazione lo consente, viene lanciato il confronto KNN shadow per confrontare e validare i risultati. Il browser non esegue né lo script shell né il binario nativo.

Questo documento descrive il flusso ricostruito dal codice esaminato. Per confermare che una specifica esecuzione sia avvenuta, occorre controllare la configurazione attiva e i log del worker.