@alucard_24/pi-codeindex 0.0.0-stage → 1.1.0

package/src/model.js

@@ -0,0 +1,71 @@
+// Download selettivo del solo encoder testo. Nessuna modifica globale a env
+// di Transformers.js; le pipeline caricano un percorso locale assoluto.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createWriteStream } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { MODEL_ID } from './backend.js';
+
+export const WEIGHT_FILES = {
+  q8: ['onnx/model_quantized.onnx', 'onnx/model_quantized.onnx_data'],
+  q4: ['onnx/model_q4.onnx', 'onnx/model_q4.onnx_data'],
+  fp16: ['onnx/model_fp16.onnx', 'onnx/model_fp16.onnx_data'],
+};
+const MULTIMODAL_KEYS = ['audio_config', 'audio_token_id', 'boa_token_id', 'boi_token_id',
+  'eoa_token_index', 'eoi_token_id', 'image_token_id', 'video_token_id', 'vision_config', 'vision_soft_tokens_per_image'];
+
+export function modelPath(config, dtype) {
+  return path.join(config.cacheDir, dtype, MODEL_ID);
+}
+
+async function exists(file) {
+  try { const st = await fs.stat(file); return st.isFile() && st.size > 0; }
+  catch (e) { if (e.code === 'ENOENT') return false; throw e; }
+}
+
+async function atomicWrite(dest, write) {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.${randomUUID()}.part`;
+  try {
+    await write(tmp);
+    await fs.rename(tmp, dest);
+  } finally { await fs.rm(tmp, { force: true }); }
+}
+
+export async function ensureTextModel(profile, config, { fetchImpl = fetch, log = (s) => process.stderr.write(`${s}\n`) } = {}) {
+  if (!Object.hasOwn(WEIGHT_FILES, profile.dtype)) throw new Error(`dtype non supportato: ${profile.dtype}`);
+  const dir = modelPath(config, profile.dtype);
+  const base = `https://huggingface.co/${MODEL_ID}/resolve/main`;
+  const files = ['tokenizer.json', 'tokenizer_config.json', ...WEIGHT_FILES[profile.dtype]];
+  for (const rel of files) {
+    const dest = path.join(dir, rel);
+    if (await exists(dest)) continue;
+    if (config.offline) throw new Error(`modalità offline: manca ${dest}; disattiva offline per scaricare i pesi`);
+    log(`[codeindex] scarico ${profile.dtype}/${rel}…`);
+    await atomicWrite(dest, async (tmp) => {
+      const response = await fetchImpl(`${base}/${rel}`, { redirect: 'follow', signal: AbortSignal.timeout(300_000) });
+      if (!response.ok || !response.body) throw new Error(`download ${rel}: HTTP ${response.status}`);
+      await pipeline(Readable.fromWeb(response.body), createWriteStream(tmp, { flags: 'wx' }));
+      const size = (await fs.stat(tmp)).size;
+      const expected = Number(response.headers.get('content-length') ?? 0);
+      if (!size || (expected && expected !== size)) throw new Error(`download incompleto ${rel}: ${size}/${expected} byte`);
+    });
+  }
+  const dest = path.join(dir, 'config.json');
+  let current = null;
+  try { current = JSON.parse(await fs.readFile(dest, 'utf8')); }
+  catch (e) { if (e.code !== 'ENOENT' && !(e instanceof SyntaxError)) throw e; }
+  if (!current) {
+    if (config.offline) throw new Error(`modalità offline: manca una config valida in ${dest}`);
+    const response = await fetchImpl(`${base}/config.json`, { signal: AbortSignal.timeout(30_000) });
+    if (!response.ok) throw new Error(`config.json: HTTP ${response.status}`);
+    current = await response.json();
+  } else if (!MULTIMODAL_KEYS.some((key) => key in current)) {
+    return dir;
+  }
+  for (const key of MULTIMODAL_KEYS) delete current[key];
+  await atomicWrite(dest, (tmp) => fs.writeFile(tmp, JSON.stringify(current, null, 2), { flag: 'wx' }));
+  return dir;
+}

package/src/present.js

@@ -0,0 +1,177 @@
+// Formattazione per l'agente: funzioni pure, nessun accesso a pi o al disco.
+// Stanno qui, e non in extension.js, perché sono l'unica parte dell'integrazione
+// che vale la pena testare con `node --test` (l'adapter resta sottile).
+
+import path from 'node:path';
+
+export const OUTLINE_MIN_LINES = 300;
+export const OUTLINE_MIN_SYMBOLS = 5;
+export const OUTLINE_MAX_SYMBOLS = 40;
+// Limite di default di `read` (DEFAULT_MAX_LINES): un `limit` a questo valore è
+// una read completa esplicita, non una lettura mirata.
+const FULL_READ_LIMIT = 2000;
+const MAX_PREVIEW_LINES = 2;
+const MAX_PREVIEW_CHARS = 160;
+
+/** 1234 -> "1.2k"; 5230 -> "5.2k". Sotto il migliaio resta il numero esatto. */
+export function fmtK(n) {
+  if (!Number.isFinite(n) || n < 0) return '?';
+  if (n < 1000) return String(Math.round(n));
+  const k = n / 1000;
+  return `${k < 10 ? k.toFixed(1) : Math.round(k)}k`;
+}
+
+/**
+ * Riga di stato per il footer. `undefined` = nessuna riga (nessun repo git).
+ * @param {{repo?: string|null, enabled?: boolean, indexing?: boolean,
+ *          progress?: {done: number, total: number}|null, chunks?: number}} s
+ */
+export function statusLine(s) {
+  if (!s?.repo) return undefined;
+  if (s.enabled === false) return 'codeindex: off';
+  if (s.indexing) {
+    const p = s.progress;
+    return p && p.total > 0
+      ? `codeindex: ${fmtK(p.done)}/${fmtK(p.total)}`
+      : 'codeindex: indicizzazione…';
+  }
+  if (s.chunks > 0) return `codeindex: ${fmtK(s.chunks)} chunk`;
+  return 'codeindex: nessun indice';
+}
+
+/**
+ * Bundle (Fase 4.5): hit + import + importatori + chiamanti euristici dei primi
+ * risultati. Formato compatto: ogni fatto è una riga, il resto è contesto.
+ */
+export function formatBundle(query, res, { contexts = 3 } = {}) {
+  const lines = [formatHitsHead(res), ''];
+  const results = res?.results ?? [];
+  results.forEach((r, i) => {
+    lines.push(`${(r.score ?? 0).toFixed(3)}  ${r.path}:${r.start}-${r.end}  [${r.kind}${r.symbols?.length ? ` · ${r.symbols[0]}` : ''}]${r.stale ? '  STALE' : ''}`);
+    const p = String(r.preview ?? '').split('\n').slice(0, MAX_PREVIEW_LINES);
+    for (const l of p) if (l.trim()) lines.push(`       ${oneLine(l)}`);
+    if (i >= contexts) return;
+    const c = r.context;
+    if (c?.imports?.length) lines.push(`       imports: ${c.imports.join(', ')}`);
+    if (c?.importers?.length) lines.push(`       imported by: ${c.importers.join(', ')}`);
+    for (const caller of c?.callers ?? []) {
+      lines.push(`       caller (heuristic): ${caller.path}:${caller.line} in ${caller.container ?? 'top level'}`);
+    }
+    if (c?.callersTruncated) lines.push('       … more callers not shown');
+  });
+  if (!results.length) {
+    lines.push('No semantic match. Try different wording, or grep for an exact identifier.');
+  } else {
+    if (results.some((r) => r.stale)) {
+      lines.push('STALE = file changed after indexing: re-read it, line numbers may have moved.');
+    }
+    lines.push('Callers are heuristic (identifier scan), not a call graph. Verify before editing.');
+  }
+  return lines.join('\n');
+}
+
+function formatHitsHead(res) {
+  const n = res?.results?.length ?? 0;
+  return `${n} result${n === 1 ? '' : 's'} in ${Math.round(res?.tookMs ?? 0)} ms` +
+    `${res?.chunks ? ` · ${fmtK(res.chunks)} chunks indexed` : ''}`;
+}
+
+/**
+ * Riga iniettata nel system prompt: rende `search_code` scopribile senza
+ * contare le query già presenti nelle dichiarazioni dei tool.
+ * Il conteggio è arrotondato perché il testo resti stabile (prompt cache).
+ */
+export function promptLine(chunks) {
+  if (!chunks || chunks < 100) return null;
+  return (
+    `Code index: ${fmtK(chunks)} chunks of this repository are embedded locally ` +
+    '(search_code). Prefer it to localize code before grep/read; grep stays best for exact strings.'
+  );
+}
+
+const oneLine = (s, n = MAX_PREVIEW_CHARS) => String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, n);
+
+/** Risultati di ricerca in forma compatta: una riga per hit + anteprima breve. */
+export function formatHits(query, res) {
+  const n = res?.results?.length ?? 0;
+  const lines = [formatHitsHead(res)];
+  for (const r of res?.results ?? []) {
+    const sym = r.symbols?.length ? ` · ${r.symbols.slice(0, 3).join(', ')}` : '';
+    const stale = r.stale ? '  STALE' : '';
+    lines.push(
+      `${(r.score ?? 0).toFixed(3)}  ${r.path}:${r.start}-${r.end}  [${r.kind}${sym}]` +
+        `  cos ${(r.cos ?? 0).toFixed(3)} lex ${(r.lex ?? 0).toFixed(2)}${stale}`,
+    );
+    const preview = String(r.preview ?? '').split('\n').slice(0, MAX_PREVIEW_LINES);
+    for (const l of preview) if (l.trim()) lines.push(`       ${oneLine(l)}`);
+  }
+  if (n === 0) {
+    lines.push(
+      'No semantic match. Try a different wording, or grep for an exact identifier — ' +
+        'the index finds concepts, not literal strings.',
+    );
+  } else {
+    if (res?.results?.some((r) => r.stale)) {
+      lines.push('STALE = file changed after indexing: re-read it, line numbers may have moved.');
+    }
+    lines.push('Read the hits you need (read with offset/limit for large files); grep for exact strings.');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Outline di un file dall'indice: solo simboli, nessun contenuto.
+ * @returns {string|null} null se il file non ha abbastanza simboli indicizzati.
+ */
+export function outlineText(relPath, lineCount, chunks, {
+  minLines = OUTLINE_MIN_LINES,
+  minSymbols = OUTLINE_MIN_SYMBOLS,
+  maxSymbols = OUTLINE_MAX_SYMBOLS,
+} = {}) {
+  if (!(lineCount > minLines)) return null;
+  const mine = (chunks ?? [])
+    .filter((c) => c.path === relPath && c.symbol && c.kind !== 'preamble')
+    .sort((a, b) => a.start - b.start);
+  const seen = new Set();
+  const picked = [];
+  for (const c of mine) {
+    if (seen.has(c.symbol)) continue;
+    seen.add(c.symbol);
+    picked.push(c);
+  }
+  if (picked.length < minSymbols) return null;
+  const shown = picked.slice(0, maxSymbols);
+  const lines = [
+    `[outline from code index · ${relPath} · ${lineCount} lines · ${picked.length} symbols]`,
+  ];
+  for (const c of shown) {
+    const range = `${c.start}-${c.end}`.padEnd(12);
+    lines.push(`${range}${c.kind.padEnd(10)}${c.symbol}`);
+  }
+  if (picked.length > shown.length) lines.push(`… ${picked.length - shown.length} more (search_code for details)`);
+  lines.push('[full file content follows]');
+  return lines.join('\n');
+}
+
+/**
+ * Decide se annotare una `read`. L'outline serve a chi legge un file intero:
+ * una read mirata (offset/limit espliciti) non lo riceve.
+ * `offset: 1`/`limit: 2000` sono la read completa scritta in modo esplicito.
+ */
+export function shouldAnnotateRead(input, lineCount, { minLines = OUTLINE_MIN_LINES } = {}) {
+  if (!(lineCount > minLines)) return false;
+  const offset = input?.offset;
+  if (offset !== undefined && offset !== null && offset > 1) return false;
+  const limit = input?.limit;
+  if (limit !== undefined && limit !== null && limit < FULL_READ_LIMIT) return false;
+  return true;
+}
+
+/** Path assoluto -> relativo al repo, o null se esce dal repo. */
+export function toRepoRel(repo, absPath) {
+  if (!repo || !absPath) return null;
+  const abs = path.resolve(absPath);
+  const rel = path.relative(repo, abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/');
+}

package/src/probe.js

@@ -0,0 +1,23 @@
+// Entry point interno, eseguito solo da doctor --probe in un processo isolato.
+import { cosine } from './embed.js';
+import { loadConfig } from './config.js';
+import { createLocalEmbedder } from './local-embed.js';
+
+let result, runtime;
+try {
+  const t0 = performance.now();
+  runtime = createLocalEmbedder((await loadConfig()).config);
+  const same = 'title: args.ts | text: export function parseArgs(argv) { return argv.slice(2); }';
+  const other = 'title: math.py | text: def factorial(n): return 1 if n < 2 else n * factorial(n - 1)';
+  const [a, b, c] = await runtime.embed([same, same, other]);
+  const cosSame = cosine(a, b);
+  const cosOther = cosine(a, c);
+  if (cosSame < 0.999 || cosOther > 0.9999) throw new Error(`smoke test discriminazione fallito: stesso=${cosSame}, diverso=${cosOther}`);
+  result = { ok: true, profile: await runtime.getProfile(), elapsedMs: Math.round(performance.now() - t0),
+    cosSame, cosOther, attempts: runtime.info().attempts };
+  await runtime.dispose();
+} catch (e) {
+  result = { ok: false, error: String(e.message ?? e), attempts: runtime?.info().attempts ?? [] };
+}
+if (process.send) process.send(result, () => process.exit(result.ok ? 0 : 1));
+else { console.log(JSON.stringify(result)); process.exitCode = result.ok ? 0 : 1; }

package/src/search.js

@@ -0,0 +1,189 @@
+// Ricerca ibrida: coseno sui vettori + overlap lessicale su path/simboli/preview.
+// Due stadi: il lessico viene valutato solo sui migliori candidati del coseno
+// (200 su 30k), così una query resta < 300 ms senza un indice invertito.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { embedQuery, getEmbeddingProfile } from './embed.js';
+import { assertCompatibleIndex } from './backend.js';
+import { indexDir, indexPaths, loadIndex } from './store.js';
+import { repoRoot, sha1 } from './util.js';
+
+export const WEIGHT_COS = 0.75;
+export const WEIGHT_LEX = 0.25;
+const CANDIDATES = 200;
+const PREVIEW_LINES = 3;
+
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'from', 'into', 'this', 'that', 'are', 'was',
+  'how', 'what', 'where', 'when', 'which', 'does', 'used', 'use', 'using',
+  'di', 'del', 'della', 'dei', 'delle', 'che', 'chi', 'cui', 'per', 'con',
+  'una', 'uno', 'gli', 'nel', 'nella', 'nei', 'come', 'dove', 'quando',
+  'viene', 'vengono', 'sono', 'essere', 'alla', 'allo', 'agli', 'sul', 'sui',
+  'la', 'le', 'lo', 'il', 'un', 'uno', 'si', 'non', 'più', 'dei', 'delle',
+]);
+
+/** camelCase/snake_case/kebab -> token minuscoli, stopword rimosse. */
+export function tokenize(text) {
+  return String(text ?? '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+
+export function lexicalOverlap(queryTokens, chunk) {
+  if (queryTokens.size === 0) return 0;
+  // Path e simboli sono segnali forti; la preview (200 char) è un segnale debole:
+  // un documento lungo che parla dell'argomento non deve battere il file che lo implementa.
+  const strong = new Set(tokenize([chunk.path, chunk.symbol ?? '', ...(chunk.symbols ?? [])].join(' ')));
+  const weak = new Set(tokenize(chunk.preview ?? ''));
+  let score = 0;
+  for (const t of queryTokens) score += strong.has(t) ? 1 : weak.has(t) ? 0.5 : 0;
+  return score / queryTokens.size;
+}
+
+function dot(a, aOff, b) {
+  let s = 0;
+  for (let i = 0; i < b.length; i++) s += a[aOff + i] * b[i];
+  return s;
+}
+
+// Cache in-process: un indice da 30k chunk pesa ~100 MB di JSON + 92 MB di vettori.
+// Rileggerlo a ogni query costerebbe centinaia di ms; lo stat di due file costa ~0,1 ms.
+// La chiave d'invalidazione è la coppia (size, mtime) dei due file dell'indice, quindi
+// anche un reindex fatto da un altro processo viene visto.
+const _cache = new Map();
+const MAX_CACHED = 2;
+
+async function stampOf(repo) {
+  const { json, bin } = indexPaths(indexDir(repo));
+  try {
+    const [a, b] = await Promise.all([fs.stat(json), fs.stat(bin)]);
+    return `${a.size}:${a.mtimeMs}:${b.size}:${b.mtimeMs}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Butta via l'indice in memoria (dopo un reindex, o alla chiusura della sessione). */
+export function invalidateSearcher(root) {
+  if (root) _cache.delete(path.resolve(root));
+  else _cache.clear();
+}
+
+export async function loadSearcher(root, { refresh = false } = {}) {
+  const repo = path.resolve(root ?? repoRoot(process.cwd()) ?? process.cwd());
+  const stamp = await stampOf(repo);
+  const hit = _cache.get(repo);
+  if (!refresh && hit && stamp && hit.stamp === stamp) return hit.value;
+
+  const { index, vectors } = await loadIndex(repo);
+  if (!index || !vectors || vectors.length === 0) {
+    throw new Error(`nessun indice per ${repo}: esegui "index" prima`);
+  }
+  const value = { repo, index, vectors };
+  if (stamp) {
+    _cache.delete(repo);
+    _cache.set(repo, { stamp, value });
+    while (_cache.size > MAX_CACHED) _cache.delete(_cache.keys().next().value);
+  }
+  return value;
+}
+
+/**
+ * L1 — provenienza: confronta l'hash su disco con quello indicizzato.
+ * Costa una lettura per file distinto (≤ k file, cap 1 MB): non dipende dal
+ * watcher, quindi è vero anche se la sessione non ha visto la modifica.
+ */
+async function markStale(repo, results) {
+  const seen = new Map();
+  for (const r of results) {
+    if (seen.has(r.path)) {
+      r.stale = seen.get(r.path);
+      continue;
+    }
+    let stale = true;
+    try {
+      const buf = await fs.readFile(path.resolve(repo, r.path));
+      stale = sha1(buf) !== r.fileHash;
+    } catch {
+      stale = true; // file sparito: non fidarsi del risultato
+    }
+    seen.set(r.path, stale);
+    r.stale = stale;
+  }
+}
+
+export async function previewOf(repo, chunk) {
+  try {
+    const abs = path.resolve(repo, chunk.path);
+    if (!abs.startsWith(repo + path.sep)) return null; // niente path fuori dal repo
+    const text = await fs.readFile(abs, 'utf8');
+    const lines = text.split('\n').slice(chunk.start - 1, Math.min(chunk.end, chunk.start - 1 + PREVIEW_LINES));
+    return lines.map((l) => l.trimEnd()).filter((l, i, arr) => l !== '' || i < arr.length - 1).join('\n');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @returns {Promise<{results:Array, tookMs:number, candidates:number}>}
+ */
+export async function search(query, { root, k = 8, pathPrefix = null, maxPerFile = 2, checkStale = false } = {}) {
+  const t0 = performance.now();
+  const { repo, index, vectors } = await loadSearcher(root);
+  assertCompatibleIndex(index, await getEmbeddingProfile());
+  const qVec = await embedQuery(query);
+  const qTokens = new Set(tokenize(query));
+  const dims = index.dims;
+
+  const scored = [];
+  for (let i = 0; i < index.chunks.length; i++) {
+    const c = index.chunks[i];
+    if (pathPrefix && !c.path.startsWith(pathPrefix)) continue;
+    scored.push({ i, cos: dot(vectors, i * dims, qVec[0]) });
+  }
+  scored.sort((a, b) => b.cos - a.cos);
+  const top = scored.slice(0, Math.min(CANDIDATES, scored.length));
+
+  const results = top.map(({ i, cos }) => {
+    const c = index.chunks[i];
+    const lex = lexicalOverlap(qTokens, c);
+    return {
+      path: c.path,
+      start: c.start,
+      end: c.end,
+      symbol: c.symbol,
+      symbols: c.symbols ?? (c.symbol ? [c.symbol] : []),
+      kind: c.kind,
+      fileHash: c.fileHash,
+      score: WEIGHT_COS * cos + WEIGHT_LEX * lex,
+      cos,
+      lex,
+    };
+  });
+  results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.start - b.start);
+  // Diversità: senza cap, un piano di 300 KB occupa tutti gli slot e nasconde il codice.
+  const perFile = new Map();
+  const final = [];
+  for (const r of results) {
+    const n = perFile.get(r.path) ?? 0;
+    if (n >= maxPerFile) continue;
+    perFile.set(r.path, n + 1);
+    final.push(r);
+    if (final.length >= k) break;
+  }
+  for (const r of final) r.preview = await previewOf(repo, r);
+  if (checkStale && final.length) await markStale(repo, final);
+
+  return {
+    repo,
+    results: final,
+    tookMs: Math.round((performance.now() - t0) * 10) / 10,
+    candidates: top.length,
+    chunks: index.chunks.length,
+    stale: final.some((r) => r.stale),
+  };
+}

package/src/service-client.js

@@ -0,0 +1,126 @@
+// Client leggero: solo JSON e socket loopback. Nessuna pipeline locale.
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { loadConfig } from './config.js';
+import { assertCompatibleIndex, validateEmbeddings } from './backend.js';
+import { serviceAddress, readServiceRecord, rpc, disconnected, serviceError } from './service-protocol.js';
+import { validateServiceConfig, validateTexts } from './service-policy.js';
+
+export function createEmbeddingClient({ env = process.env, settings = () => loadConfig({ env }),
+  workerFile = new URL('./service-worker.js', import.meta.url), startupTimeoutMs = 10_000, requestTimeoutMs = 15 * 60_000 } = {}) {
+  let config = null, configLoading = null, starting = null, pinned = null;
+  let pending = 0, error = null, remote = null;
+  async function getConfig() {
+    if (config) return config;
+    if (!configLoading) configLoading = Promise.resolve().then(settings).then((loaded) => {
+      config = validateServiceConfig(loaded.config);
+      return config;
+    });
+    try { return await configLoading; } finally { configLoading = null; }
+  }
+  async function probe(address) {
+    const record = await readServiceRecord(address);
+    if (!record) return { record: null };
+    try {
+      const response = await rpc(address, record, { op: 'status' }, { timeoutMs: 2000 });
+      return { record, status: response.result };
+    } catch (e) {
+      if (disconnected(e)) return { record: null };
+      if (e.code === 'SERVICE_STOPPING') return { record, status: { running: false } };
+      throw e;
+    }
+  }
+  async function start(address) {
+    if (starting) return starting;
+    starting = (async () => {
+      let launchError, childRunning = false, launches = 0, lastLaunchAt = 0;
+      const launch = () => {
+        launches++; childRunning = true; lastLaunchAt = Date.now();
+        const child = fork(workerFile instanceof URL ? fileURLToPath(workerFile) : workerFile,
+          [address.directory, String(address.port)], { detached: true, execArgv: [], env,
+            stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+        child.on('error', (e) => { launchError = e; childRunning = false; });
+        child.on('exit', () => { childRunning = false; });
+        child.on('message', (message) => {
+          if (message?.ready === false && message.code !== 'EADDRINUSE') launchError = serviceError(message.code ?? 'START_FAILED', message.error);
+        });
+        child.unref(); child.channel?.unref();
+      };
+      const deadline = Date.now() + startupTimeoutMs;
+      while (Date.now() < deadline) {
+        if (launchError) throw launchError;
+        const { record, status } = await probe(address);
+        if (record && status.running) return record;
+        // Il vecchio processo tiene la porta durante dispose. Non tentare
+        // un secondo modello mentre quel processo sta ancora liberando VRAM.
+        if (!record && !childRunning && launches < 3 && Date.now() - lastLaunchAt >= 100) launch();
+        await delay(40);
+      }
+      throw serviceError('START_FAILED', `servizio locale non avviabile su 127.0.0.1:${address.port}: porta occupata o avvio fallito. Controlla service status e servicePort. Nessun fallback in-process.`);
+    })();
+    try { return await starting; } finally { starting = null; }
+  }
+  function remember(info) { if (info) remote = { ...info, lastSeenAt: Date.now() }; }
+  async function call(op, payload = {}) {
+    const active = await getConfig();
+    const address = serviceAddress(active);
+    pending++;
+    error = null;
+    try {
+      let record = await readServiceRecord(address);
+      if (!record) record = await start(address);
+      let response;
+      const request = { op, config: active, expectedProfile: pinned, ...payload };
+      try { response = await rpc(address, record, request, { timeoutMs: requestTimeoutMs }); }
+      catch (e) {
+        // Questi errori provano che l'inferenza non è iniziata. Un crash
+        // dopo l'invio non viene ritentato automaticamente.
+        if (!['ECONNREFUSED', 'SERVICE_STOPPING'].includes(e.code)) throw e;
+        record = await start(address);
+        response = await rpc(address, record, request, { timeoutMs: requestTimeoutMs });
+      }
+      remember(response.info);
+      const profile = response.info?.profile;
+      if (!profile) throw serviceError('BAD_FRAME', 'il servizio non ha restituito il profilo del modello');
+      if (pinned) {
+        try { assertCompatibleIndex(pinned, profile); }
+        catch { throw serviceError('PROFILE_CHANGED', 'profilo del servizio cambiato: riavvia pi e verifica/reindicizza; nessun vettore accettato'); }
+      }
+      pinned ??= Object.freeze({ ...profile });
+      return response.result;
+    } catch (e) {
+      remember(e.info);
+      error = e.message;
+      throw e;
+    } finally { pending--; }
+  }
+  return {
+    getProfile: async () => { await call('profile'); return pinned; },
+    embed: async (texts, { normalize = true } = {}) => {
+      if (Array.isArray(texts) && !texts.length) return [];
+      validateTexts(texts, normalize);
+      const rows = await call('embed', { texts, normalize });
+      return validateEmbeddings(rows, texts.length).map((row) => Float32Array.from(row));
+    },
+    info: () => ({ profile: pinned, config, loading: pending > 0, attempts: (remote?.attempts ?? []).map((a) => ({ ...a })),
+      error, shared: true,
+      warnings: pinned?.device === 'cpu' && config && !['auto', 'cpu'].includes(config.device)
+        ? [`fallback CPU esplicitamente consentito: richiesto ${config.device}, riutilizzato il servizio ${pinned.device}/${pinned.dtype}`] : [],
+      service: remote ? { pid: remote.pid, lastSeenAt: remote.lastSeenAt } : null }),
+    status: async () => {
+      const address = serviceAddress(await getConfig());
+      const record = await readServiceRecord(address);
+      if (!record) return { running: false, shared: true, port: address.port };
+      try { return (await rpc(address, record, { op: 'status' }, { timeoutMs: 2000 })).result; }
+      catch (e) { if (disconnected(e)) return { running: false, shared: true, port: address.port }; throw e; }
+    },
+    stop: async () => {
+      const address = serviceAddress(await getConfig());
+      const record = await readServiceRecord(address);
+      if (!record) return { stopping: false };
+      try { return (await rpc(address, record, { op: 'stop' }, { timeoutMs: 5000 })).result; }
+      catch (e) { if (disconnected(e)) return { stopping: false }; throw e; }
+    },
+  };
+}

package/src/service-policy.js

@@ -0,0 +1,33 @@
+import path from 'node:path';
+import { ENV_KEYS, validateConfig } from './config.js';
+import { assertCompatibleIndex, backendPlan, formatProfile, webgpuBackendOf } from './backend.js';
+import { MAX_TEXTS, MAX_TEXT_BYTES, serviceError } from './service-protocol.js';
+
+export function validateServiceConfig(config) {
+  validateConfig(config, 'client del servizio');
+  if (Object.keys(ENV_KEYS).some((key) => !Object.hasOwn(config, key))) throw serviceError('BAD_CONFIG', 'configurazione client incompleta');
+  if (!path.isAbsolute(config.cacheDir) || !path.isAbsolute(config.serviceDir)) throw serviceError('BAD_CONFIG', 'cacheDir e serviceDir devono essere assoluti');
+  return Object.freeze({ ...config });
+}
+
+export function assertServiceCompatible(config, activeConfig, profile, expectedProfile) {
+  const permitted = backendPlan(config, [{ device: profile.device, available: true }]).some((p) =>
+    p.device === profile.device && p.dtype === profile.dtype &&
+    (p.device !== 'webgpu' || config.webgpuBackend === webgpuBackendOf(profile)));
+  const differs = ['cacheDir', 'cpuThreads', 'serviceIdleMs'].filter((key) => config[key] !== activeConfig[key]);
+  if (!permitted || differs.length) {
+    throw serviceError('PROFILE_CONFLICT', `servizio condiviso già configurato per ${formatProfile(profile)}${differs.length ? `; impostazioni diverse: ${differs.join(', ')}` : ''}. Nessun secondo modello avviato. Usa /codeindex service status; per cambiare profilo, service stop quando inattivo e riavvia pi.`);
+  }
+  if (expectedProfile) {
+    try { assertCompatibleIndex(expectedProfile, profile); }
+    catch { throw serviceError('PROFILE_CHANGED', `profilo del servizio cambiato dopo una riconnessione: ${formatProfile(profile)}. Riavvia pi e verifica/reindicizza; nessun vettore è stato accettato.`); }
+  }
+}
+
+export function validateTexts(texts, normalize) {
+  if (!Array.isArray(texts) || !texts.length || texts.length > MAX_TEXTS || texts.some((t) => typeof t !== 'string')) {
+    throw serviceError('BAD_TEXTS', `embedding: attesi da 1 a ${MAX_TEXTS} testi`);
+  }
+  if (typeof normalize !== 'boolean') throw serviceError('BAD_TEXTS', 'normalize deve essere booleano');
+  if (texts.reduce((n, t) => n + Buffer.byteLength(t), 0) > MAX_TEXT_BYTES) throw serviceError('BAD_TEXTS', `batch di embedding troppo grande (massimo ${MAX_TEXT_BYTES} byte)`);
+}