@alucard_24/pi-codeindex 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 1.1.0
+
+### Novità
+
+- Modello di embedding in un servizio locale condiviso tra processi pi e CLI:
+  una sola pipeline per endpoint, avvio automatico, inferenze serializzate e
+  coda limitata. Nessun fallback in-process in caso di errore del servizio.
+- Rilascio del modello dopo inattività (default 5 minuti), configurabile con
+  `serviceIdleMs` / `CODEINDEX_SERVICE_IDLE_MS`.
+- `/codeindex service status` e `/codeindex service stop`, disponibili anche
+  dalla CLI. Autenticazione locale, verifica del profilo dopo riconnessione e
+  rifiuto dei conflitti di configurazione senza creare un secondo modello.
+- Indicizzazione e sincronizzazione anche nelle cartelle senza repository Git.
+  Home e radice del disco richiedono consenso esplicito in ogni sessione.
+- Diagnostica, configurazione e documentazione aggiornate; test di concorrenza,
+  crash, shutdown e prove opt-in con modello reale.
+
+### Aggiornamento
+
+Chiudere e riaprire i vecchi processi pi dopo l'aggiornamento: le copie del
+modello caricate dal vecchio runtime in-process non vengono liberate dal
+nuovo servizio. Per cambiare il profilo di un servizio già attivo usare
+`/codeindex service stop` quando inattivo, oppure attendere il timeout idle.
+I probe espliciti di doctor restano isolati e possono caricare un modello
+aggiuntivo. Endpoint diversi permettono deliberatamente istanze separate.
+
+Il servizio è stato verificato su Linux x64 con CPU, CUDA, WebGPU automatico
+e WebGPU/Vulkan; DirectML/Windows e CoreML/macOS restano da verificare sulle
+rispettive piattaforme. Le misure storiche Fase 5–7 non sono nuovi benchmark
+del servizio condiviso.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alucard24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,443 @@
-# Temporary Holding Version
+# pi-codeindex
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Indice semantico locale del codice per l'agente pi: embedding con
+**EmbeddingGemma 2** (ONNX, servizio locale condiviso) e ricerca ibrida
+(coseno + lessico) che restituisce `path:righe` + simbolo + anteprima.
+Una sola copia del modello fra processi pi/CLI sullo stesso endpoint;
+nessun servizio remoto o database. Indice: due file in
+`~/.cache/pi-codeindex/<sha1(repo)>/`.
+
+## Requisiti
+
+- Node 22+ (testato su 26.5.1).
+- CPU sempre disponibile come profilo base nelle build native supportate.
+- GPU opzionale: CUDA su Linux x64, WebGPU dove incluso nel binding,
+  DirectML su Windows, CoreML su macOS. Non tutte le combinazioni modello,
+  driver e hardware sono verificate: vedi la matrice sotto.
+
+## Installazione
+
+### Da npm, solo su richiesta
+
+```bash
+pi -e npm:@alucard_24/pi-codeindex@1.0.0
+```
+
+Carica il pacchetto per questa invocazione, senza aggiungerlo alle impostazioni
+globali di pi. Dalla sessione puoi usare `/codeindex configure` e
+`/codeindex doctor`. I pesi vengono scaricati solo al primo utilizzo del modello;
+CUDA e Vulkan richiedono i setup opzionali descritti sotto.
+
+Il pacchetto npm include codice, setup, schema, README, licenza e query di
+esempio. Il repository GitHub resta privato; piano di lavoro, report completi,
+harness sperimentale e test non sono inclusi nel tarball npm.
+
+### Dal sorgente (sviluppo)
+
+```bash
+npm install
+npm run setup-gpu     # solo GPU NVIDIA: scarica il provider CUDA e lo configura
+```
+
+`setup-gpu.sh` è **solo Linux x64** e richiede CUDA 13 + `patchelf`.
+Va rieseguito se un aggiornamento/reinstallazione sostituisce il provider.
+DirectML, CoreML e WebGPU usano i provider inclusi nel binding nativo;
+non richiedono questo script CUDA.
+
+Il pacchetto espone anche il binario `pi-codeindex`: gli esempi
+`node src/cli.js ...` possono essere eseguiti come `pi-codeindex ...`
+quando il binario è sul PATH. `pi-codeindex setup-gpu` avvia il setup CUDA.
+Nessun postinstall scarica i pesi e nessuna configurazione globale di pi viene
+modificata dal pacchetto.
+
+## Embedding e backend
+
+Il modello **EmbeddingGemma 2** gira in un servizio locale condiviso avviato
+automaticamente al primo utilizzo, anche dall'indicizzazione automatica.
+I client pi/CLI non caricano una pipeline propria. I soli pesi testo vengono
+scaricati e riutilizzati fra repository; dopo il primo download è possibile
+lavorare offline. Il codice da embeddare viaggia solo sul loopback locale,
+non viene inviato al server dei pesi o a un'API di embedding remota.
+
+| `device` | Default `dtype: auto` | Stato |
+|---|---|---|
+| `cpu` | `q8` | inferenza reale verificata su Linux x64 |
+| `cuda` | `fp16` | inferenza reale verificata su NVIDIA/Linux x64; setup opzionale |
+| `webgpu` | `fp16` | inferenza reale verificata su questa macchina Linux; supporto hardware/driver variabile |
+| `dml` | `fp16` | DirectML/Windows: integrazione e policy testate, hardware non verificato |
+| `coreml` | `fp16` | CoreML/macOS: integrazione e policy testate, hardware non verificato |
+
+**Vulkan è selezionabile come backend nativo di WebGPU**, non come provider
+ONNX autonomo: usa `device: "webgpu"` + `webgpuBackend: "vulkan"` dopo il setup
+opzionale sotto. `device: "vulkan"` resta un errore esplicativo. Con
+`webgpuBackend: "auto"` decide Dawn: non si garantisce Vulkan e non lo si
+presenta come forzato. Stato e metadati distinguono `webgpu→vulkan/fp16` da
+`webgpu→auto/fp16`.
+Un provider presente nel binding non garantisce compatibilità, velocità,
+utilizzo della GPU dedicata o copertura totale del grafo: ORT può eseguire
+alcuni operatori su CPU. Gli smoke test non sostituiscono un benchmark di
+retrieval/performance per piattaforma. `q4` è disponibile ma il drift non è
+validato sull'eval.
+
+**Auto:** Linux prova CUDA → WebGPU → CPU; Windows DirectML → WebGPU → CPU;
+macOS CoreML → WebGPU → CPU. I provider assenti vengono saltati; una prova del
+modello reale deve riuscire prima che il profilo venga fissato. Tentativi e
+fallback sono visibili nei log e nello stato/avvisi dell'estensione.
+Un device forzato fallisce per default; `fallback: "cpu"` autorizza il ripiego.
+Il fallback avviene solo all'inizializzazione, mai durante l'embedding di un
+indice già iniziato. La prima riconciliazione di un processo inizializza il
+modello anche se l'indice era caldo; i vecchi tempi di re-index sotto indicati
+precedono questo cambiamento.
+
+### WebGPU con Vulkan forzato (opzionale, Linux x64)
+
+```bash
+npm run setup-vulkan
+CODEINDEX_OFFLINE=true node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
+CODEINDEX_DEVICE=webgpu CODEINDEX_WEBGPU_BACKEND=vulkan pi -e ./src/extension.js
+```
+
+Il setup richiede **compilatore C++17, header Node/N-API, `tar`, `patchelf` e
+rete** per scaricare i piccoli sorgenti del binding. Non compila ORT/Dawn e
+non richiede CUDA o il Vulkan SDK: riusa il runtime precompilato con WebGPU;
+per eseguire serve il driver Vulkan. Header fuori dai percorsi standard:
+`npm run setup-vulkan -- --node-headers /percorso/include/node`.
+
+Il binding Node standard 1.30.0 non espone il selettore Dawn. Il setup
+compila un binding opzionale da un commit ORT fissato e con hash dei sorgenti
+verificati. Binding e copia del runtime (con SONAME distinto) restano in
+`~/.cache/pi-codeindex/native/`: **nessuna modifica a `node_modules`**, nessun
+provider standard sostituito. Il backend aggiunto ha nome unico e priorità
+negativa: viene usato solo da una sessione che lo richiede esplicitamente.
+Prima del caricamento si verificano gli hash; un controllo negativo obbligatorio
+rifiuta i binding che ignorano il selettore. Manca il setup, il runtime è
+cambiato o non esiste un adapter Vulkan? Errore, non WebGPU automatico nascosto.
+Il fallback CPU resta solo quello già autorizzato da `fallback: "cpu"`.
+
+Il setup è idempotente; dopo un cambio di runtime può essere necessario
+rieseguirlo. `pi-codeindex setup-vulkan` è equivalente. Riavvia pi dopo setup
+o cambi di profilo. Il backend WebGPU entra nell'identità dell'indice: cambiare
+`auto` ↔ `vulkan` richiede re-index. Con `device: "auto"` il selettore riguarda
+solo l'eventuale tentativo WebGPU: CUDA può ancora essere scelto prima.
+
+Windows richiederebbe anche una build ORT/Dawn con Vulkan abilitato: **non
+implementata/verificata** da questo setup. AMD e Intel richiedono prove sulle
+rispettive GPU. Nessuna promessa di vantaggio prestazionale rispetto a CUDA.
+Le prove con il modello completo richiedono VRAM libera; il processo `doctor`
+riporta l'errore e non termina applicazioni GPU altrui per liberarla.
+
+Test opzionali reali, dopo setup e download dei pesi fp16:
+`CODEINDEX_TEST_VULKAN=1 node --test test/vulkan-integration.test.js`.
+La suite normale non richiede GPU né compila addon. Verificati su questa
+macchina Linux x64 / RTX 5070 Ti: EmbeddingGemma fp16, indice incrementale,
+ricerca su fixture e coesistenza con i provider standard. Queste prove non
+sostituiscono un benchmark di qualità o prestazioni su altri hardware.
+
+## Servizio condiviso e memoria
+
+Il primo client sceglie il profilo secondo la configurazione; gli altri
+riutilizzano la stessa pipeline se quel profilo è consentito. Un profilo
+incompatibile, una cache pesi diversa o valori diversi di `cpuThreads` o
+`serviceIdleMs` danno errore: **nessun secondo modello e nessun fallback
+in-process**. Un device forzato può riutilizzare un servizio CPU solo con
+`fallback: cpu`, con avviso esplicito. Le richieste sono serializzate, con
+massimo 16 richieste attive/in coda; ogni batch contiene al massimo 128 testi
+e 2 MiB di testo. La saturazione della coda produce un errore, non un altro
+worker. Un crash interrompe la richiesta corrente; un uso successivo può
+riavviare il servizio, verificando il profilo già fissato dal client.
+
+Dopo **5 minuti senza operazioni sul modello** il processo termina e l'OS
+libera RAM/VRAM native. `status` non rinnova il timer. Chiudere/disabilitare
+una singola sessione non arresta un modello che può servire altri processi.
+Per liberarlo subito, quando non ci sono inferenze in corso:
+
+```text
+/codeindex service status
+/codeindex service status --json
+/codeindex service stop
+```
+
+Gli stessi comandi funzionano come `node src/cli.js service status|stop`.
+Stop viene rifiutato se ci sono richieste attive/in coda; non interrompe altri
+client. Il servizio si riavvierà al prossimo utilizzo del modello. Nessun
+avvio al login, servizio di sistema o modifica alle impostazioni globali di pi.
+
+Il listener è solo `127.0.0.1`, con porta deterministica per la directory
+utente e autenticazione tramite token in `~/.cache/pi-codeindex/service/`
+(directory 0700, record 0600 su POSIX). Il binding esclusivo della porta
+impedisce due avvii simultanei. Una porta occupata da un altro programma dà
+un errore: `servicePort` consente una scelta esplicita. Usa gli stessi
+`serviceDir`/`servicePort` in tutti i client: cambiarli crea endpoint distinti
+e permette deliberatamente più modelli. Non condividere il token o la directory.
+
+Restano per-processo le cache degli indici, dei vettori e dei grafi: il servizio
+elimina le copie del **modello**, non tutta la memoria di pi. Dopo l'aggiornamento
+**chiudi e riapri i vecchi processi pi**: i modelli già caricati dal vecchio
+codice in-process non possono essere liberati dal nuovo servizio.
+
+Verifica reale opt-in, con pesi già in cache (offline), due processi client,
+indice/ricerca e uscita idle:
+
+```bash
+CODEINDEX_TEST_SERVICE=1 CODEINDEX_DEVICE=cuda node --test test/service-integration.test.js
+# Oppure cpu/q8, oppure WebGPU con CODEINDEX_WEBGPU_BACKEND=vulkan dopo setup-vulkan.
+```
+
+Questi test non sono un nuovo benchmark Fase 5–7. La piattaforma iniziale di
+verifica del servizio è Linux x64; Windows/DirectML e macOS/CoreML richiedono
+verifica sulle rispettive macchine.
+
+## Configurazione
+
+Dentro pi:
+
+```text
+/codeindex configure                     menu interattivo + conferma salvataggio
+/codeindex config                        valori effettivi, provenienza e percorso
+/codeindex config set device webgpu
+/codeindex config set dtype fp16
+/codeindex config set webgpuBackend vulkan  solo WebGPU, setup-vulkan richiesto
+/codeindex config set fallback cpu
+/codeindex config unset device           ripristina la scelta automatica
+/codeindex service status                processo condiviso, profilo e memoria
+/codeindex service stop                  rilascia il modello quando inattivo
+/codeindex doctor                        inventario, senza inferenza/download
+/codeindex doctor --probe --device webgpu prova reale isolata (può scaricare i pesi)
+```
+
+La configurazione è **della macchina**, non della sessione pi:
+`$XDG_CONFIG_HOME/pi-codeindex/config.json` oppure
+`~/.config/pi-codeindex/config.json` (`%APPDATA%/pi-codeindex/config.json`
+su Windows). `CODEINDEX_CONFIG=/percorso/config.json` sceglie un file diverso,
+anche per un singolo progetto; nessun file del repository viene letto
+implicitamente. Non vengono modificate le impostazioni di pi.
+Precedenza: **default < file < ambiente**. Il menu salva solo i campi cambiati,
+non gli override d'ambiente. JSON malformato/chiavi sconosciute producono errori,
+non default silenziosi. Schema per editor: [config.schema.json](config.schema.json).
+
+```json
+{
+  "device": "auto",
+  "dtype": "auto",
+  "fallback": "error",
+  "offline": false,
+  "cpuThreads": 0
+}
+```
+
+| Campo | Valori | Override ambiente |
+|---|---|---|
+| `device` | `auto`, `cpu`, `cuda`, `webgpu`, `dml`, `coreml` | `CODEINDEX_DEVICE` |
+| `dtype` | `auto`, `q8`, `q4`, `fp16` | `CODEINDEX_DTYPE` |
+| `webgpuBackend` | `auto` (default), `vulkan` forzato; riguarda solo WebGPU | `CODEINDEX_WEBGPU_BACKEND` |
+| `fallback` | `error` (default), `cpu`; riguarda device forzati | `CODEINDEX_FALLBACK` |
+| `offline` | booleano; niente download, errore se mancano pesi | `CODEINDEX_OFFLINE=true\|false\|1\|0` |
+| `cacheDir` | cache pesi, default `~/.cache/pi-codeindex/text-model` | `CODEINDEX_MODEL_CACHE` |
+| `cpuThreads` | 0 = default ORT, oppure 1–256; non limita la GPU | `CODEINDEX_CPU_THREADS` |
+| `serviceIdleMs` | default 300000 (5 min), da 1000 a 86400000 ms | `CODEINDEX_SERVICE_IDLE_MS` |
+| `serviceDir` | directory privata condivisa, default `~/.cache/pi-codeindex/service` | `CODEINDEX_SERVICE_DIR` |
+| `servicePort` | 0 = deterministica, oppure 1024–65535; solo loopback | `CODEINDEX_SERVICE_PORT` |
+
+**Riavvia pi con un nuovo processo** dopo una modifica: non si cambia pipeline
+nel mezzo di un run. Se il servizio ha già un profilo/configurazione diversi,
+usa anche `service stop` quando inattivo, oppure attendi l'uscita idle.
+Prima di aggiornare a un protocollo incompatibile, arresta il vecchio servizio.
+Il menu non riavvia né reindicizza da solo. Device, dtype
+e backend WebGPU effettivi sono salvati nell'indice; se diversi, la ricerca rifiuta di mescolare
+i vettori e chiede un re-index. Gli indici precedenti senza `device` vengono
+ricostruiti alla prossima indicizzazione.
+
+Da shell, senza avviare pi:
+
+```bash
+node src/cli.js config show
+node src/cli.js config set device cpu
+node src/cli.js config set cpuThreads 4
+node src/cli.js doctor --probe --device cpu --json
+node src/cli.js doctor --probe --all       # prove sequenziali dei provider presenti
+node src/cli.js doctor --probe --device webgpu --webgpu-backend vulkan
+CODEINDEX_DEVICE=cuda CODEINDEX_DTYPE=fp16 pi -e ./src/extension.js
+```
+
+`doctor` senza `--probe` non carica/scarica il modello. Le prove reali girano
+in subprocessi isolati con timeout di 120 s per backend; `--all` può scaricare
+più varianti. Ogni provider forzato viene provato senza fallback, per non
+attribuire alla GPU un successo ottenuto in CPU. Usa `offline: true` per provarle solo dalla cache. Un crash nativo
+di una prova non abbatte pi. I probe restano esplicitamente isolati e **possono
+caricare una copia aggiuntiva del modello** mentre il servizio è attivo: arresta
+prima il servizio se vuoi evitare questo picco. Anche la pipeline ordinaria è
+ora isolata, nel worker condiviso. Smoke del menu e dei comandi via RPC, senza
+chiamate LLM e con cache modello temporanea/offline: `CODEINDEX_TEST_RPC=1 node --test test/config-rpc.test.js` (richiede
+`pi` sul PATH; usa un file config temporaneo, non modifica quello utente).
+
+## Comandi
+
+```bash
+node src/cli.js index   [--root DIR] [--max-files 5000] [--max-bytes 200] [--force]
+node src/cli.js status  [--root DIR]
+node src/cli.js search  "query" [--k 8] [--path-prefix src/] [--stale] [--bundle] [--json]
+node src/cli.js eval    [--file eval/queries.jsonl] [--json]
+node src/cli.js embed-test
+```
+
+- `index` è incrementale: confronta l'hash di ogni file e riusa i vettori dei
+  chunk invariati. Salvataggio atomico; una cache di ripresa evita di
+  ricalcolare tutto se il run viene interrotto.
+- `search` legge il codice dal disco solo per i risultati finali e non esce
+  mai dal repo.
+- `eval` misura recall@3/@8 e latenza sulle query della fixture.
+
+## Uso dentro pi
+
+```bash
+# pacchetto npm: solo questa invocazione, nessuna configurazione globale
+pi -e npm:@alucard_24/pi-codeindex@1.0.0
+
+# in sviluppo, dalla directory del progetto
+pi -e ./src/extension.js
+```
+
+Cosa aggiunge:
+
+- **`search_code`** — ricerca semantica (`query`, `k` 1–30, `path_prefix`,
+  `context`) che restituisce `path:start-end`, simbolo e anteprima. Non
+  sostituisce `grep`.
+  - i risultati il cui file è cambiato dopo l'indicizzazione sono marcati
+    `STALE` (hash su disco, non fiducia nel watcher);
+  - `context: "bundle"` aggiunge import, importatori e fino a 5 chiamanti
+    **euristici** dei primi 3 risultati: un round-trip invece di una catena
+    `grep`+`read`.
+- **outline su `read`** — se leggi un file > 300 righe con ≥ 5 simboli indicizzati
+  e senza `offset`/`limit` mirati, ricevi un blocco `[outline from code index]`
+  con i simboli e i loro range (max 40, ~3,5% di caratteri in più).
+- **riga di stato** nel footer (`codeindex: 5.2k chunk`, `codeindex: 1.2k/4.8k`
+  durante l'indicizzazione).
+- **`/codeindex status|reindex [--force]|enable|disable|config|configure|doctor`**. `disable` spegne
+  tutto: tool, outline, riga di stato, riga nel system prompt, watcher e
+  indicizzazione in corso. Lo stato è persistito nel branch della sessione;
+  una sessione nuova riparte attiva.
+- **indicizzazione automatica** all'avvio della sessione, in background,
+  single-flight, interrompibile, con cap 5.000 file / 200 MB.
+- **sincronizzazione**: watcher ricorsivo con debounce 800 ms, invalidazione
+  diretta da `write`/`edit` e controllo dopo `bash`: sweep `git status` nei
+  repository, riconciliazione incrementale nelle cartelle senza Git. Una
+  riconciliazione riusa i vettori dei file intatti (misurato nei repository:
+  1 chunk re-embedded su 3 dopo una modifica, 920 ms fino all'indice aggiornato).
+
+Se il modello non è scaricabile o il reindex fallisce, `search_code` risponde
+con lo stato reale e la sessione continua.
+
+### Cartelle senza Git
+
+Git è opzionale. Nei repository la radice resta quella restituita da Git,
+anche avviando pi da una sottocartella. Altrimenti viene usata **esattamente
+la directory da cui avvii pi**: non viene creato `.git`, non servono commit
+né un remote. `/codeindex status` mostra radice e modalità.
+
+In modalità cartella la scansione esclude le directory nascoste e le consuete
+directory di dipendenze/output (`node_modules`, `dist`, `build`, `out`,
+`vendor`, `target`, `coverage`, `venv`, `__pycache__`); non segue i symlink.
+Restano i limiti di estensione, dimensione, 5.000 file e 200 MB. Le esclusioni
+sono quelle fisse della scansione locale: **senza Git i file `.gitignore`
+non vengono interpretati**. Nei repository continua a valere `git ls-files`
+con le esclusioni Git.
+
+Il watcher gestisce anche rename/cancellazioni di directory; dopo `bash`
+viene accodata una riconciliazione senza ricalcolare i vettori invariati.
+Se il watcher non è disponibile, la riconciliazione viene accodata anche
+all'inizio di un nuovo prompt. `/codeindex reindex` resta disponibile per
+aggiornare manualmente l'indice; `--force` ricalcola tutti i vettori.
+
+Per evitare scansioni involontarie dell'intera macchina, nella **home** e
+nella **radice del disco**, se non sono repository Git, l'indice parte spento.
+Avvia pi dalla cartella del progetto oppure abilitalo esplicitamente con
+`/codeindex enable`; nelle due cartelle protette il consenso va ripetuto a
+ogni avvio della sessione. Nessuna nuova configurazione globale è necessaria.
+
+## Cosa indicizza
+
+JS/TS/TSX/JSX, Python, Go, Rust, C, C++, C#, PowerBuilder (.srw/.sru/…),
+Markdown. Chunk declaration-aware, con fusione dei chunk piccoli (Markdown fino
+a 80 righe; codice solo micro-chunk ≤6 righe). Esclusi: binari, file >1 MB,
+minified, lockfile, `.pbl`/`.pbt`/`.pbw`.
+
+## Numeri misurati (runtime originale in-process, RTX 5070 Ti, fp16)
+
+Queste misure precedono il servizio condiviso e non ne misurano memoria,
+latenza IPC o prestazioni con client concorrenti.
+
+| Repo | File | Chunk | Primo indice | Re-index |
+|---|---|---|---|---|
+| `pi.dev-ext` | 373 | 5.230 | 44 s | 169 ms |
+| `Strata` | 2.872 | 29.974 | ~2–5 min | 737 ms |
+
+Su CPU q8 (`pi.dev-ext`): 18m28s il primo indice, 143 ms il secondo.
+Ricerca a indice caldo: p50 32 ms. Recall@3 sulla fixture: 5/8.
+
+Dentro pi: cache in-process dell'indice (stat dei due file come chiave), quindi
+11,5 ms a caldo su `pi.dev-ext` e **40 ms su `Strata`** (30k chunk), contro ~1,2 s
+di caricamento modello alla prima query di un processo nuovo.
+Outline su un file da 3.713 righe: **+3,5% caratteri** sulla read.
+
+## Misura (giro completo)
+
+I file e i comandi di questa sezione si riferiscono al checkout di sviluppo:
+piano, report completi e harness non vengono distribuiti nel pacchetto npm.
+Il riepilogo e i limiti delle misure sono riportati qui senza estenderne lo scope.
+
+`RESULTS.md` riporta l'esperimento A (pi nudo) vs C (pi + indice) su 10 task per
+repo × 3 ripetizioni: mediana dei delta **−25,4% token su `Strata`** e **−9,7% su
+`pi.dev-ext`**, ma costo totale **−12,3%** e **−12,9%**: sotto la soglia del 15%
+del gate primario. Il verdetto è nel file: **gate non superato**, progetto fermo
+per la regola scritta in `PLAN.md`. Il braccio B (OpenLore) non è stato eseguito:
+nessun claim comparativo.
+
+La Fase 6 ha ripetuto la misura con un budget di **80 tool call** per sessione
+(`RESULTS-FASE6.md`): costo **−23,2%** su `Strata` e **−19,2%** su `pi.dev-ext`,
+ma successo **27/30 vs 28/30** su `Strata`. Tutti i fallimenti sono run tagliati
+dal cap; il criterio pre-registrato `C ≥ A` non è soddisfatto per una run, quindi
+quel gate resta non superato.
+
+La Fase 7 (`RESULTS-FASE7.md`, 80 coppie appaiate per repo, ipotesi più debole
+pre-registrata prima dei run) supera il gate che chiede **solo di non spendere
+più**: costo appaiato **−22,1%** su `Strata` (CI unilaterale [−29,3%, −14,1%]) e
+−21,5% su `pi.dev-ext`, successo **74/80 vs 74/80** e 79/80 vs 80/80. La soglia
+del **15%** resta non misurata: quello che è dimostrato è "in sessione con budget
+di 80 tool call il costo non aumenta e il successo non peggiora oltre 10pp".
+
+```bash
+node scripts/experiment.mjs --repo ~/AI-Projects/Strata --repeat 8 \
+  --max-tool-calls 80 --out /tmp/exp5-strata
+node scripts/analyze-experiment.mjs --runs /tmp/exp5-strata --runs /tmp/exp5-pidev
+```
+
+## Limiti noti
+
+- Il chunker è euristico (regex per famiglia): nessun parser AST, nessun
+  call graph. Gli errori di confine sono possibili e non etichettati.
+- I chiamanti del bundle sono euristici (scansione dell'identificatore, non un
+  call graph): su un campione di 61 casi la precisione misurata è 92%. Il livello
+  import è più stretto: solo specifiche che risolvono a un unico file, 29/30 edge
+  senza ambiguità su `Strata`.
+- I documenti di piano Markdown competono con il codice nella ricerca: il cap
+  di 2 risultati per file e il peso maggiore di path/simbolo mitigano, non
+  eliminano il problema.
+- Query in italiano su codice con identificatori inglesi funzionano meno bene
+  delle query in inglese.
+- Device e `dtype` fanno parte dell'identità dei vettori: cambiarli richiede
+  un re-index. Lo storage v2 lega manifest e vettori con SHA-256: anche un
+  salvataggio concorrente/incompleto non viene scambiato per un indice valido.
+  Gli indici vecchi senza digest richiedono ricostruzione. La directory è
+  unica per repo: processi con profili diversi possono sostituirla o renderla
+  temporaneamente indisponibile, mai riutilizzare vettori incompatibili.
+- DirectML e CoreML richiedono ancora smoke test su Windows/macOS; WebGPU è
+  verificato solo sulla macchina Linux disponibile, non su tutte le GPU.
+- I pesi sono ancora scaricati dalla revisione `main` del modello; il cache non
+  viene aggiornato automaticamente. Prima di un rilascio riproducibile occorre
+  fissare uno snapshot dei pesi e verificarne l'integrità.
+
+## Licenza
+
+Il codice di pi-codeindex è distribuito sotto licenza [MIT](LICENSE).
+Dipendenze, sorgenti upstream scaricati dal setup e pesi del modello mantengono
+le rispettive licenze; non sono inclusi nel tarball del pacchetto.

package/config.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pi-codeindex — configurazione embedding locali",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "device": { "enum": ["auto", "cpu", "cuda", "webgpu", "dml", "coreml"], "default": "auto", "description": "Per Vulkan forzato usa webgpu con webgpuBackend: vulkan. auto prova i provider presenti per piattaforma, poi CPU." },
+    "dtype": { "enum": ["auto", "q8", "q4", "fp16"], "default": "auto", "description": "auto: q8 su CPU, fp16 sugli altri provider. Cambiarlo richiede reindex." },
+    "webgpuBackend": { "enum": ["auto", "vulkan"], "default": "auto", "description": "Backend Dawn quando il provider effettivo è webgpu. vulkan forza Vulkan e richiede setup-vulkan (inizialmente Linux x64). Non influenza CPU/CUDA/DirectML/CoreML." },
+    "fallback": { "enum": ["error", "cpu"], "default": "error", "description": "Fallback consentito per un device forzato; auto include sempre CPU." },
+    "offline": { "type": "boolean", "default": false },
+    "cacheDir": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Cache dei pesi. Supporta ~/; i percorsi relativi sono risolti dal cwd." },
+    "cpuThreads": { "type": "integer", "minimum": 0, "maximum": 256, "default": 0, "description": "0 usa il default di ONNX Runtime; non limita la GPU." },
+    "serviceDir": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Directory privata del servizio condiviso. Default ~/.cache/pi-codeindex/service; non cambiarla fra sessioni se vuoi condividere il modello." },
+    "servicePort": { "type": "integer", "anyOf": [{ "const": 0 }, { "minimum": 1024, "maximum": 65535 }], "default": 0, "description": "0 sceglie una porta loopback deterministica dalla directory del servizio. Cambiarla crea un endpoint distinto." },
+    "serviceIdleMs": { "type": "integer", "minimum": 1000, "maximum": 86400000, "default": 300000, "description": "Inattività prima di terminare il processo e liberare il modello (default 5 minuti). Status non rinnova il timer." }
+  }
+}

package/eval/queries.jsonl

@@ -0,0 +1,8 @@
+{"query":"dove viene stimato il numero di token BPE di un messaggio","expects":["bpe-token-estimator"],"why":"estimatore token BPE dedicato"}
+{"query":"come viene applicata una modifica ancorata a un file","expects":["anchored-edit"],"why":"motore delle modifiche ancorate"}
+{"query":"ricerca nella history canonica delle sessioni","expects":["history-service","history-source-reader","context-history-tool"],"why":"lettura e ricerca della history"}
+{"query":"coordinamento della compaction tra più sessioni","expects":["compaction-coordinator"],"why":"coordinatore della compaction"}
+{"query":"lock per evitare rebase concorrenti di una sessione","expects":["rebase-lock"],"why":"lock di rebase"}
+{"query":"quali artefatti vengono conservati e per quanto tempo","expects":["ARTIFACTS.md","artifacts"],"why":"documentazione sugli artefatti"}
+{"query":"marker di omissione per non riesportare dati già visti","expects":["egress"],"why":"gestione egress e marker di omissione"}
+{"query":"indicizzazione incrementale delle sessioni salvate","expects":["session-indexer"],"why":"indice incrementale delle sessioni"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@alucard_24/pi-codeindex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Indice semantico locale del codice per pi (EmbeddingGemma 2, ONNX)",
+  "license": "MIT",
+  "author": "Alucard24",
+  "repository": { "type": "git", "url": "git+https://github.com/Alucard24/pi-codeindex.git" },
+  "homepage": "https://www.npmjs.com/package/@alucard_24/pi-codeindex",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "main": "./src/extension.js",
+  "bin": { "pi-codeindex": "src/cli.js" },
+  "files": ["src", "scripts/setup-gpu.sh", "scripts/setup-vulkan.mjs", "scripts/vulkan-sources.json", "eval/queries.jsonl", "config.schema.json", "README.md", "CHANGELOG.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "test": "node --test 'test/*.test.js'",
+    "embed-test": "node src/cli.js embed-test",
+    "setup-gpu": "bash scripts/setup-gpu.sh",
+    "setup-vulkan": "node scripts/setup-vulkan.mjs",
+    "doctor": "node src/cli.js doctor"
+  },
+  "keywords": ["pi-package", "embeddings", "code-search"],
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/extension.js"
+    ]
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.3.2",
+    "onnxruntime-node": "1.30.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  }
 }

package/scripts/setup-gpu.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Abilita il provider CUDA di onnxruntime-node (Linux x64, GPU NVIDIA).
+#
+# 1. scarica i binari del provider CUDA se mancano (script ufficiale ORT);
+# 2. trova le librerie CUDA 13 richieste dal provider 1.30 (libcublasLt.so.13,
+#    libcudart.so.13, libcurand.so.10, ...);
+# 3. scrive un RUNPATH nel .so del provider: così la GPU funziona senza
+#    esportare LD_LIBRARY_PATH (necessario perché l'estensione pi gira
+#    dentro un processo già avviato).
+#
+# Idempotente. Da rieseguire dopo `npm install` (node_modules viene ricreato).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+if ! node -e 'process.exit(process.platform === "linux" && process.arch === "x64" ? 0 : 1)'; then
+  echo "[gpu] setup CUDA disponibile solo su Linux x64; usa doctor per i backend della tua piattaforma." >&2
+  exit 1
+fi
+# Funziona anche con dipendenze npm hoisted, non solo con node_modules locale.
+ORT="$(node --input-type=module - "$ROOT/package.json" <<'JS'
+import { createRequire } from 'node:module';
+import path from 'node:path';
+console.log(path.dirname(createRequire(process.argv[2]).resolve('onnxruntime-node/package.json')));
+JS
+)"
+PROVIDER="$(find "$ORT/bin" -path '*/linux/x64/libonnxruntime_providers_cuda.so' | head -1 || true)"
+BIN_DIR="$(dirname "${PROVIDER:-$ORT/bin/napi-v6/linux/x64/x}")"
+
+if [[ ! -f "$PROVIDER" ]]; then
+  echo "[gpu] provider CUDA assente: lo scarico (≈270 MB)…"
+  node "$ORT/script/install.js" --onnxruntime-node-install=cuda12
+  PROVIDER="$BIN_DIR/libonnxruntime_providers_cuda.so"
+fi
+
+find_cuda_lib() {
+  local d
+  for d in \
+    "${CUDA13_LIB:-}" \
+    "$HOME"/.local/cuda-13*/targets/*/lib \
+    /usr/local/cuda-13*/targets/*/lib \
+    /usr/local/cuda/lib64 \
+    "$HOME"/.local/venv-cu13/lib/python*/site-packages/nvidia/cu13/lib \
+    /opt/cuda/lib64; do
+    [[ -n "$d" && -e "$d/libcublasLt.so.13" ]] && { echo "$d"; return 0; }
+  done
+  return 1
+}
+
+CUDA_LIB="$(find_cuda_lib || true)"
+if [[ -z "$CUDA_LIB" ]]; then
+  echo "[gpu] ERRORE: non trovo libcublasLt.so.13 (serve il runtime CUDA 13)." >&2
+  echo "      Installa CUDA 13 o imposta CUDA13_LIB=/percorso/lib." >&2
+  exit 1
+fi
+
+command -v patchelf >/dev/null || { echo "[gpu] ERRORE: patchelf non installato." >&2; exit 1; }
+
+echo "[gpu] CUDA libs: $CUDA_LIB"
+patchelf --set-rpath "$CUDA_LIB" "$PROVIDER"
+if LD_LIBRARY_PATH= ldd "$PROVIDER" | grep -q "not found"; then
+  echo "[gpu] ERRORE: dipendenze non risolte:" >&2
+  LD_LIBRARY_PATH= ldd "$PROVIDER" | grep "not found" >&2
+  exit 1
+fi
+echo "[gpu] ok: provider CUDA pronto (nessun LD_LIBRARY_PATH richiesto)"