talos-code 0.0.1 → 0.2.0

package/vendor/harness-ui/src/mcp-registry.mjs

@@ -0,0 +1,157 @@
+/**
+ * mcp-registry.mjs — FASE E del piano `elegant-spinning-dongarra.md`,
+ * seconda fetta (29/8): dove vive la configurazione dei server MCP
+ * per-workspace, e il trust che decide se un server dichiarato può
+ * davvero connettersi. `hook-registry.mjs` letto per intero come
+ * precedente diretto prima di scrivere questo file — stesso design,
+ * per lo stesso motivo: un comando esterno arbitrario (qui: un intero
+ * server a lunga vita, con i SUOI tool, non solo un controllo rapido)
+ * non deve MAI partire senza un consenso esplicito dell'owner, e quel
+ * consenso resta legato al CONTENUTO della dichiarazione (hash), non
+ * al nome.
+ *
+ * ⛔⛔ Due cartelle DIVERSE, stesso motivo di hook-registry.mjs:
+ * - `.harness-ui-mcp.json` vive DENTRO il workspace (come hooks.json,
+ *   AGENTS.md) — "quali server MCP servono questo progetto" è una
+ *   proprietà del progetto, non della macchina.
+ * - il trust vive FUORI, accanto a server.mjs (stesso pattern di
+ *   `.automations/` e del trust degli hook).
+ *
+ * ⛔⛔⛔ L'`allowlist` per server è OBBLIGATORIA nello schema, non
+ * opzionale — a differenza di `filtraToolMcp` in mcp-client.mjs (che
+ * accetta qualunque array, anche vuoto, perché non è compito suo
+ * imporre una policy). Qui SÌ: un server dichiarato senza allowlist è
+ * un file MALFORMATO, rifiutato prima ancora di poter connettersi —
+ * "mai un tool MCP remoto esposto senza filtro" (piano madre, §2.2)
+ * è applicato al punto più a monte
+ * possibile, non lasciato alla disciplina di chi integra dopo.
+ *
+ * Il PROTOCOLLO (connettersi, elencare, chiamare) resta interamente
+ * in mcp-client.mjs — questo file non lo importa e non lo usa: solo
+ * configurazione e trust, stesso confine "qui solo X, mai Y" già
+ * documentato nella testa di mcp-client.mjs stesso.
+ */
+import { createHash } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+
+export class McpRegistryError extends Error {
+  constructor(message, code = 'MCP_CONFIG_INVALID') {
+    super(message);
+    this.name = 'McpRegistryError';
+    this.code = code;
+  }
+}
+
+const NOME_FILE_MCP = '.harness-ui-mcp.json';
+
+/**
+ * Legge `<cartella>/.harness-ui-mcp.json`. Un progetto senza server
+ * dichiarati è uno stato valido — mai un errore, torna `{ server: [] }`.
+ * Uno schema malformato invece È un errore dichiarato (mai un server
+ * fantasma silenziosamente ignorato, stesso principio di caricaHooks).
+ */
+export async function caricaServerMcp({ cartella }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const percorso = join(cartella, NOME_FILE_MCP);
+  let testo;
+  try {
+    testo = await readFileFn(percorso, 'utf8');
+  } catch (errore) {
+    if (errore?.code === 'ENOENT') return { server: [] };
+    throw new McpRegistryError(`Impossibile leggere ${NOME_FILE_MCP}: ${errore.message}`, 'MCP_CONFIG_READ_FAILED');
+  }
+  let dati;
+  try {
+    dati = JSON.parse(testo);
+  } catch {
+    throw new McpRegistryError(`${NOME_FILE_MCP} non è un JSON valido`, 'MCP_CONFIG_MALFORMED');
+  }
+  if (!dati || !Array.isArray(dati.server)) {
+    throw new McpRegistryError(`${NOME_FILE_MCP} deve avere un campo "server" (array)`, 'MCP_CONFIG_MALFORMED');
+  }
+  const server = dati.server.map((voce, indice) => {
+    if (typeof voce?.id !== 'string' || voce.id.length === 0) {
+      throw new McpRegistryError(`server[${indice}] manca di "id" (stringa non vuota)`, 'MCP_CONFIG_MALFORMED');
+    }
+    if (typeof voce.comando !== 'string' || voce.comando.length === 0) {
+      throw new McpRegistryError(`server[${indice}] ("${voce.id}") manca di "comando" (stringa non vuota)`, 'MCP_CONFIG_MALFORMED');
+    }
+    if (voce.argomenti !== undefined && (!Array.isArray(voce.argomenti) || !voce.argomenti.every((a) => typeof a === 'string'))) {
+      throw new McpRegistryError(`server[${indice}] ("${voce.id}") ha "argomenti" non valido — atteso un array di stringhe`, 'MCP_CONFIG_MALFORMED');
+    }
+    if (!Array.isArray(voce.allowlist) || voce.allowlist.length === 0 || !voce.allowlist.every((n) => typeof n === 'string' && n.length > 0)) {
+      throw new McpRegistryError(`server[${indice}] ("${voce.id}") manca di "allowlist" (array non vuoto di nomi tool) — un server MCP non si dichiara senza dire quali tool sono ammessi`, 'MCP_CONFIG_MALFORMED');
+    }
+    const argomenti = voce.argomenti ?? [];
+    const hash = createHash('sha256').update(JSON.stringify({ comando: voce.comando, argomenti, allowlist: voce.allowlist })).digest('hex');
+    return { id: voce.id, comando: voce.comando, argomenti, allowlist: voce.allowlist, hash };
+  });
+  return { server };
+}
+
+function percorsoTrust(cartellaTrust, serverId) {
+  // ⛔ serverId arriva da un file scritto dall'owner (.harness-ui-mcp.json),
+  // ma è comunque un input esterno: mai costruire un percorso da una
+  // stringa non validata come nome file — stesso principio già in uso
+  // in hook-registry.mjs/workspace-files.mjs.
+  if (typeof serverId !== 'string' || serverId.length === 0 || /[\\/]|\.\./.test(serverId)) {
+    throw new McpRegistryError('serverId non valido — un nome, non un percorso', 'MCP_SERVER_ID_INVALID');
+  }
+  return join(cartellaTrust, `${serverId}.json`);
+}
+
+/**
+ * Un server è fidato SOLO se il registro persistito porta lo STESSO
+ * hash della dichiarazione attuale (comando+argomenti+allowlist) — un
+ * server il cui contenuto è cambiato torna automaticamente "non
+ * fidato", senza bisogno di un'azione esplicita di sfiducia: il trust
+ * è legato al CONTENUTO, non al nome. Stesso comportamento di
+ * verificaTrust in hook-registry.mjs.
+ */
+export async function verificaTrustMcp({ cartellaTrust, serverId, hash }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let testo;
+  try {
+    testo = await readFileFn(percorsoTrust(cartellaTrust, serverId), 'utf8');
+  } catch {
+    return false; // mai fidato per default: assente = non fidato, non un errore
+  }
+  try {
+    const dati = JSON.parse(testo);
+    return dati?.hash === hash;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Registra il trust — chiamata SOLO da un'azione owner esplicita (la
+ * rotta HTTP dedicata, mai automatica dal ciclo dell'agente o
+ * dall'avvio di una sessione).
+ */
+export async function fidaServerMcp({ cartellaTrust, serverId, hash }, deps = {}) {
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  await mkdirFn(cartellaTrust, { recursive: true });
+  await writeFileFn(percorsoTrust(cartellaTrust, serverId), JSON.stringify({ hash, fidatoIl: new Date().toISOString() }), 'utf8');
+  return { fidato: true };
+}
+
+/**
+ * Il punto d'ingresso per chi avvia una sessione (session-registry.mjs):
+ * carica i server dichiarati, tiene SOLO quelli fidati (stesso
+ * fail-closed di hook-registry.mjs — un server non fidato semplicemente
+ * non compare, mai un errore che blocca l'avvio della sessione: la
+ * sessione parte comunque, solo senza quel server), e torna l'elenco
+ * pronto per essere connesso da mcp-client.mjs.
+ */
+export async function serverMcpFidati({ cartella, cartellaTrust }, deps = {}) {
+  const { server } = await caricaServerMcp({ cartella }, deps);
+  const fidati = [];
+  for (const s of server) {
+    const fidato = await verificaTrustMcp({ cartellaTrust, serverId: s.id, hash: s.hash }, deps);
+    if (fidato) fidati.push(s);
+  }
+  return { fidati, nonFidati: server.filter((s) => !fidati.includes(s)) };
+}

package/vendor/harness-ui/src/mcp-session.mjs

@@ -0,0 +1,177 @@
+/**
+ * mcp-session.mjs — FASE E del piano `elegant-spinning-dongarra.md`,
+ * terza fetta (29/8): il punto che UNISCE `mcp-registry.mjs` (quali
+ * server sono dichiarati e fidati) e `mcp-client.mjs` (il protocollo)
+ * in quello che una sessione REALE offre al kernel — `toolMcp` +
+ * `chiamaToolMcpFn`, esattamente la forma che `talosLavora` accetta
+ * (vedi `AVM-harness/.../talosHarness.mjs`, commit `a902af7`).
+ *
+ * ⛔ A differenza degli hook (`costruisciHookFn`, letto per intero
+ * prima di scrivere questo file): un hook si legge PIGRAMENTE, alla
+ * prima tool-call, perché serve solo quando un evento capita. I tool
+ * MCP invece devono essere NOTI PRIMA della prima chiamata al modello
+ * (finiscono nello schema `tools` della richiesta) — questo file
+ * connette tutti i server fidati EAGERMENTE, una volta, prima che
+ * `talosLavora` parta.
+ *
+ * ⛔⛔⛔ Piu' server possono esporre un tool con lo STESSO nome (`read_file`
+ * su due server diversi non e' un caso raro — sono processi
+ * indipendenti, non sanno l'uno dell'altro). Il nome esposto al
+ * modello e' quindi SEMPRE prefissato `mcp__<serverId>__<toolName>`
+ * (stessa convenzione dell'ecosistema MCP, non inventata qui) — un
+ * dispatcher interno lo demux nel client/nome originali giusti,
+ * mai un'ambiguita' silenziosa fra due server.
+ *
+ * Un server che non parte (comando sbagliato, dipendenza mancante)
+ * non impedisce MAI alla sessione di avviarsi — stesso principio
+ * "mai un blocco silenzioso, degrada" gia' in uso per gli hook: viene
+ * saltato, e il suo fallimento e' registrato per chi chiama (mai
+ * inghiottito senza traccia).
+ */
+import {
+  caricaServerMcp as caricaServerMcpReale,
+  serverMcpFidati as serverMcpFidatiReale,
+} from './mcp-registry.mjs';
+import { schemaIngressoAttrezzo } from './tool-schema-normalize.mjs';
+import {
+  chiamaToolMcp as chiamaToolMcpReale,
+  connettiServerMcp as connettiServerMcpReale,
+  elencaToolMcp as elencaToolMcpReale,
+  filtraToolMcp as filtraToolMcpReale,
+} from './mcp-client.mjs';
+
+const SEPARATORE = '__';
+const PREFISSO = `mcp${SEPARATORE}`;
+
+/** Pura: costruisce il nome esposto al modello. Un test la esercita senza connettere nulla. */
+export function nomeEspostoMcp(serverId, nomeTool) {
+  return `${PREFISSO}${serverId}${SEPARATORE}${nomeTool}`;
+}
+
+/** Tetto della partenza in parallelo: oltre, si aprirebbero troppi processi figli in un colpo all'avvio di una sessione. */
+export const CONCORRENZA_AVVIO_MCP_MASSIMA = 8;
+
+/*
+ * ⭐ 14/09 (F07 della review) — la scoperta dei tool era SERIALE: N server fidati costavano la SOMMA dei loro avvii,
+ *   e ogni avvio è un processo figlio che fa handshake, cioè attesa, non calcolo. Misurato su quattro server d'eco:
+ *   mediana **121 ms** in fila contro **46 ms** a quattro per volta.
+ * ⛔ Resta SPENTA di serie (`1` = il comportamento di prima, byte per byte): un server MCP di terzi può avere un
+ *   avvio pesante, e far partire più processi insieme sulla macchina di qualcun altro non è una scelta che prendo io.
+ *   Chi la vuole la accende con `TALOS_MCP_STARTUP_CONCURRENCY`.
+ * ⛔ Qualunque valore storto — vuoto, «due», 0, -3, 2.5 — torna **1**, mai un errore: una variabile d'ambiente scritta
+ *   male non deve impedire a una sessione di partire.
+ */
+export function concorrenzaAvvioMcp(env = process.env) {
+  const grezzo = env?.TALOS_MCP_STARTUP_CONCURRENCY;
+  if (typeof grezzo !== 'string' && typeof grezzo !== 'number') return 1;
+  const numero = Number(String(grezzo).trim());
+  if (!Number.isInteger(numero) || numero < 1) return 1;
+  return Math.min(numero, CONCORRENZA_AVVIO_MCP_MASSIMA);
+}
+
+/**
+ * Connette OGNI server fidato del workspace, scopre e filtra i suoi
+ * tool con la sua allowlist (mai "tutto ciò che offre" — la stessa
+ * garanzia che `filtraToolMcp` già dà, applicata qui a ogni server
+ * dichiarato), e torna `{toolMcp, chiamaToolMcpFn, falliti, chiudiTutti}`
+ * pronto per `talosLavora`.
+ *
+ * `falliti`: `{serverId, errore}[]` — i server che NON sono partiti,
+ * mai inghiottiti in silenzio (chi chiama decide se avvisare l'owner).
+ * `chiudiTutti()`: chiude OGNI connessione aperta — va chiamato quando
+ * la sessione finisce, altrimenti il processo figlio del server resta
+ * vivo (stesso rischio già noto per ogni sottoprocesso spawnato).
+ */
+export async function preparaToolMcpPerSessione({ cartella, cartellaTrust }, deps = {}) {
+  const serverMcpFidatiFn = deps.serverMcpFidatiFn ?? serverMcpFidatiReale;
+  const connettiServerMcpFn = deps.connettiServerMcpFn ?? connettiServerMcpReale;
+  const elencaToolMcpFn = deps.elencaToolMcpFn ?? elencaToolMcpReale;
+  const filtraToolMcpFn = deps.filtraToolMcpFn ?? filtraToolMcpReale;
+  const chiamaToolMcpFnReale = deps.chiamaToolMcpFn ?? chiamaToolMcpReale;
+
+  let fidati = [];
+  try {
+    ({ fidati } = await serverMcpFidatiFn({ cartella, cartellaTrust }));
+  } catch {
+    // ⭐ stesso principio degli hook: un registro che non si legge non blocca la sessione, degrada a "nessun server".
+    return { toolMcp: [], chiamaToolMcpFn: null, falliti: [], chiudiTutti: async () => {} };
+  }
+
+  const toolMcp = [];
+  const instradamento = new Map(); // nomeEsposto -> { client, nomeOriginale }
+  const connessioni = []; // { client, chiudi } — per chiudiTutti
+  const falliti = [];
+
+  /** L'avvio di UN server: non lancia mai — un fallimento è un esito come un altro, da comporre in ordine più sotto. */
+  async function avviaUnServer(server) {
+    let client;
+    let chiudi;
+    try {
+      ({ client, chiudi } = await connettiServerMcpFn({ comando: server.comando, argomenti: server.argomenti, nome: `talos-harness-${server.id}` }));
+    } catch (errore) {
+      // un server che non parte non ferma gli altri, ne' la sessione
+      return { server, errore: errore instanceof Error ? errore.message : String(errore) };
+    }
+    let tuttiITool;
+    try {
+      tuttiITool = await elencaToolMcpFn({ client });
+    } catch (errore) {
+      // la connessione resta aperta (chiusa comunque da chiudiTutti), ma zero tool da questo server
+      return { server, client, chiudi, errore: `elenco tool fallito: ${errore instanceof Error ? errore.message : String(errore)}` };
+    }
+    return { server, client, chiudi, tool: filtraToolMcpFn(tuttiITool, server.allowlist) };
+  }
+
+  /*
+   * ⛔ L'ORDINE del risultato non dipende da chi finisce prima: gli esiti si depositano nella casella del loro server e
+   *   si compongono dopo, in fila. Senza, `toolMcp` cambierebbe ordine a ogni avvio a seconda di quale processo figlio
+   *   è stato più svelto — e con due server che espongono lo stesso attrezzo cambierebbe anche quale vince a schermo.
+   */
+  const concorrenza = Math.max(1, Math.min(deps.concorrenza ?? concorrenzaAvvioMcp(deps.env), CONCORRENZA_AVVIO_MCP_MASSIMA));
+  const esiti = new Array(fidati.length).fill(null);
+  let prossimo = 0;
+  async function unLavoratore() {
+    while (prossimo < fidati.length) {
+      const indice = prossimo;
+      prossimo += 1;
+      esiti[indice] = await avviaUnServer(fidati[indice]);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concorrenza, fidati.length) }, () => unLavoratore()));
+
+  for (const esito of esiti) {
+    if (!esito) continue;
+    if (esito.chiudi) connessioni.push({ client: esito.client, chiudi: esito.chiudi });
+    if (esito.errore) {
+      falliti.push({ serverId: esito.server.id, errore: esito.errore });
+      continue;
+    }
+    for (const t of esito.tool) {
+      const nomeEsposto = nomeEspostoMcp(esito.server.id, t.name);
+      /*
+       * ⛔ Stessa cura degli attrezzi Forge, e qui serve ancora di più: questo
+       * schema arriva da un server MCP di TERZI, che non abbiamo scritto noi e
+       * non possiamo correggere. Passarlo intatto a un motore che ne costruisce
+       * una grammatica fa fallire l'intera richiesta — non solo quell'attrezzo.
+       */
+      toolMcp.push({ name: nomeEsposto, description: t.description, inputSchema: schemaIngressoAttrezzo(t.inputSchema) });
+      instradamento.set(nomeEsposto, { client: esito.client, nomeOriginale: t.name });
+    }
+  }
+
+  const chiamaToolMcpFn = toolMcp.length > 0
+    ? async (nomeEsposto, argomenti) => {
+      const voce = instradamento.get(nomeEsposto);
+      if (!voce) throw new Error(`tool MCP "${nomeEsposto}" non è fra quelli connessi in questa sessione`);
+      return chiamaToolMcpFnReale({ client: voce.client }, voce.nomeOriginale, argomenti);
+    }
+    : null;
+
+  const chiudiTutti = async () => {
+    for (const { chiudi } of connessioni) {
+      try { await chiudi(); } catch { /* un server che non chiude pulito non deve bloccare la chiusura degli altri */ }
+    }
+  };
+
+  return { toolMcp, chiamaToolMcpFn, falliti, chiudiTutti };
+}

package/vendor/harness-ui/src/memory-store.mjs

@@ -0,0 +1,227 @@
+/**
+ * memory-store.mjs — FASE N, sesto sistema (30/8), piano
+ * `elegant-spinning-dongarra.md`. Owner: "TUTTI i 5 sistemi rimasti, uno
+ * dopo l'altro".
+ *
+ * ⛔⛔⛔ GLOBALE, non per-progetto — stesso principio di notes-store.mjs/
+ * tasks-store.mjs. Letto alla fonte: `mobile/src/lib/tools/memoryWriteTools.ts`
+ * + `readTools.ts` + `chatDatabaseSchema.ts` (`talos_memories`) +
+ * `stationFacades.ts`/`chatController.ts` (l'implementazione VERA dietro
+ * l'interfaccia del tool, non presunta). Lo schema mobile ha uno
+ * `scope_type` a tre livelli (global/project/session), ma il CHIAMANTE
+ * del tool lo fissa a `'global'` SEMPRE, verificato in
+ * `chatController.ts`: "«ricordati che preferisco le risposte brevi»
+ * non vale solo in questa conversazione" — questo porto riflette solo
+ * ciò che il tool espone davvero, non l'intero schema del deposito.
+ *
+ * ⛔ `status` (active/disabled/quarantined/rejected nello schema mobile)
+ * NON portato: quella macchina a stati è per la STAZIONE mobile
+ * (moderazione manuale) — verificato in `stationFacades.ts`,
+ * `TalosMemoryWriteSources` non ha un `setStatus`. `memory_delete`
+ * desktop fa una cancellazione VERA (mobile stesso chiama
+ * `deleteMemory`, un hard delete — confermato alla fonte, non un
+ * cambio di stato), stesso schema di notes_delete/tasks_delete.
+ *
+ * ⭐⭐⭐ L'UNICA logica genuinamente nuova rispetto a Notes/Tasks: la
+ * DEDUPLICAZIONE per titolo. Owner mobile, 2026-08-07: "«no, ricordati
+ * invece che...» produceva una seconda memoria accanto alla prima" — la
+ * memoria è l'unica superficie in cui un duplicato non è disordine, è
+ * una contraddizione che si autoalimenta a ogni conversazione futura.
+ * `creaMemoria` cerca PRIMA per titolo (case-insensitive, spazi
+ * ignorati) e torna la voce ESISTENTE con `duplicato:true` invece di
+ * scriverne una seconda.
+ *
+ * ⛔ Diverso da mobile in UN dettaglio, dichiarato: mobile `create()`
+ * NON torna un id ("l'ha detto il typecheck, non io" — un vincolo
+ * accidentale della sua implementazione, non una scelta di design,
+ * verificato leggendo il commento originale). Questo store non ha
+ * quel vincolo: `creaMemoria` torna sempre l'id, per coerenza con
+ * notes-store.mjs/tasks-store.mjs (il messaggio di successo desktop
+ * include l'id, come "Saved the note «X» (id Y)." — mobile non lo fa
+ * per un accidente della sua repository, non per principio).
+ *
+ * ⛔ Stessa CONVENZIONE DI CHIAMATA di notes-store.mjs/tasks-store.mjs
+ * (`funzione({cartella, ...}, deps={})`). Un file JSON per memoria
+ * (stessa classe di bug — riscrittura invece di accodamento — già
+ * evitata altrove, session-store.mjs).
+ */
+import { randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+import { idArchivioValido } from './id-archivio.mjs';
+
+const TITOLO_MASSIMO = 80;
+const CONTENUTO_MASSIMO = 600;
+const GENERI = Object.freeze(['preference', 'project_fact', 'procedure', 'policy_note']);
+
+/** ⭐ Stesso pattern REALE di `.automations/`/`.notes-store/`/`.tasks-store/`: il nome che `server.mjs` userà per il percorso di default. */
+export const CARTELLA_MEMORIA = '.memory-store';
+
+export class MemoryStoreError extends Error {
+  constructor(message, code = 'MEMORY_INVALID') {
+    super(message);
+    this.name = 'MemoryStoreError';
+    this.code = code;
+  }
+}
+
+function percorsoDi(cartella, id) {
+  // ⛔ 14/09: l'id arriva da fuori (indirizzo HTTP, attrezzo del modello) — un id fuori grammatica non nomina nessun file e
+  //   torna `null`, mai un `join` che con `..` uscirebbe dalla cartella. Vedi id-archivio.mjs.
+  if (!idArchivioValido(id)) return null;
+  return join(cartella, `${id}.json`);
+}
+
+function normalizzaTitoloPerConfronto(titolo) {
+  return titolo.trim().toLowerCase();
+}
+
+function validaTitolo(title) {
+  if (typeof title !== 'string' || title.trim().length === 0 || title.length > TITOLO_MASSIMO) {
+    throw new MemoryStoreError(`title deve avere 1-${TITOLO_MASSIMO} caratteri`, 'MEMORY_INVALID');
+  }
+  return title.trim();
+}
+
+function validaContenuto(content) {
+  if (typeof content !== 'string' || content.trim().length === 0 || content.length > CONTENUTO_MASSIMO) {
+    throw new MemoryStoreError(`content deve avere 1-${CONTENUTO_MASSIMO} caratteri`, 'MEMORY_INVALID');
+  }
+  return content.trim();
+}
+
+function validaGenere(kind) {
+  if (!GENERI.includes(kind)) {
+    throw new MemoryStoreError(`kind deve essere uno fra ${GENERI.join('/')}`, 'MEMORY_INVALID');
+  }
+  return kind;
+}
+
+/* ⛔ 11/09 — CHI ha scritto questa memoria: stesso principio e stesso default di notes-store.mjs/tasks-store.mjs. */
+const ORIGINI = Object.freeze(['persona', 'modello']);
+
+function validaOrigine(origine) {
+  if (!ORIGINI.includes(origine)) {
+    throw new MemoryStoreError(`origine deve essere una fra ${ORIGINI.join('/')}`, 'MEMORY_INVALID');
+  }
+  return origine;
+}
+
+/** La forma PUBBLICA di una memoria — l'unica che esce da questo prodotto, uguale per ogni superficie che la mostra. */
+export function formaPubblicaMemoria(voce) {
+  return {
+    id: voce.id,
+    titolo: voce.titolo,
+    contenuto: voce.contenuto,
+    genere: voce.genere,
+    creataAlle: voce.creataAlle ?? null,
+    aggiornataAlle: voce.aggiornataAlle ?? null,
+    origine: ORIGINI.includes(voce.origine) ? voce.origine : 'modello',
+  };
+}
+
+/** Più recentemente aggiornate per prime. Cartella assente ⇒ `[]`, mai un errore. */
+export async function elencaMemorie({ cartella }, deps = {}) {
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  let nomi;
+  try {
+    nomi = await readdirFn(cartella);
+  } catch {
+    return [];
+  }
+  const voci = [];
+  for (const nome of nomi) {
+    if (!nome.endsWith('.json')) continue;
+    try {
+      voci.push(JSON.parse(await readFileFn(join(cartella, nome), 'utf8')));
+    } catch { /* una voce corrotta non deve nascondere le altre */ }
+  }
+  return voci.sort((a, b) => b.aggiornataAlle.localeCompare(a.aggiornataAlle) || a.id.localeCompare(b.id));
+}
+
+/** Un id assente torna `null`, mai un'eccezione. */
+export async function leggiMemoria({ cartella, id }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const percorso = percorsoDi(cartella, id);
+  if (!percorso) return null; // ⛔ 14/09: id fuori grammatica = «non c'è», mai una lettura fuori dalla cartella
+  try {
+    return JSON.parse(await readFileFn(percorso, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Cerca per titolo esatto (case/spazi-insensitive) — usata dalla deduplicazione, mai per il modello direttamente. */
+export async function trovaMemoriaPerTitolo({ cartella, title }, deps = {}) {
+  const cercato = normalizzaTitoloPerConfronto(title);
+  const tutte = await elencaMemorie({ cartella }, deps);
+  return tutte.find((m) => normalizzaTitoloPerConfronto(m.titolo) === cercato) ?? null;
+}
+
+/**
+ * PURA — stesso confine di `cercaVoci` in library-store.mjs: chi
+ * chiama carica l'elenco (I/O), questa funzione filtra (nessun I/O,
+ * un test la esercita con un array letterale). Sottostringa
+ * case-insensitive su titolo O contenuto — `memory_search` mobile non
+ * documenta un algoritmo più sofisticato di questo (nessuna fonte
+ * trovata per un ranking/fuzzy match), quindi non se ne inventa uno.
+ */
+export function cercaMemorie(memorie, { query, limit = 5 } = {}) {
+  const cercato = String(query ?? '').trim().toLowerCase();
+  const trovate = cercato === ''
+    ? []
+    : memorie.filter((m) => m.titolo.toLowerCase().includes(cercato) || m.contenuto.toLowerCase().includes(cercato));
+  return { memorie: trovate.slice(0, limit), totale: trovate.length };
+}
+
+/**
+ * @returns `{voce, duplicato}` — `duplicato:true` quando esiste già una
+ * memoria con lo STESSO titolo: torna quella esistente, MAI ne scrive
+ * una seconda (la dedup è la ragion d'essere di questa funzione, non
+ * un dettaglio).
+ * @throws {MemoryStoreError} MEMORY_INVALID PRIMA di ogni I/O.
+ */
+export async function creaMemoria({ cartella, title, content, kind = 'preference', origine = 'modello' }, deps = {}) {
+  const titolo = validaTitolo(title);
+  const contenuto = validaContenuto(content);
+  const genere = validaGenere(kind);
+  const daChi = validaOrigine(origine);
+  const readdirFn = deps.readdirFn ?? fsp.readdir;
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const gemello = await trovaMemoriaPerTitolo({ cartella, title: titolo }, { readdirFn, readFileFn });
+  if (gemello) return { voce: gemello, duplicato: true };
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const clockFn = deps.clockFn ?? (() => new Date());
+  const ora = clockFn().toISOString();
+  const voce = { id: randomUUID(), titolo, contenuto, genere, origine: daChi, creataAlle: ora, aggiornataAlle: ora };
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoDi(cartella, voce.id), JSON.stringify(voce, null, 2), 'utf8');
+  return { voce, duplicato: false };
+}
+
+/** Solo i campi passati cambiano. @throws {MemoryStoreError} MEMORY_NOT_FOUND se l'id non esiste. */
+export async function aggiornaMemoria({ cartella, id, title, content, kind }, deps = {}) {
+  const readFileFn = deps.readFileFn ?? fsp.readFile;
+  const mkdirFn = deps.mkdirFn ?? fsp.mkdir;
+  const writeFileFn = deps.writeFileFn ?? fsp.writeFile;
+  const clockFn = deps.clockFn ?? (() => new Date());
+  const voce = await leggiMemoria({ cartella, id }, { readFileFn });
+  if (!voce) throw new MemoryStoreError(`nessuna memoria con id ${id}`, 'MEMORY_NOT_FOUND');
+  if (title !== undefined) voce.titolo = validaTitolo(title);
+  if (content !== undefined) voce.contenuto = validaContenuto(content);
+  if (kind !== undefined) voce.genere = validaGenere(kind);
+  voce.aggiornataAlle = clockFn().toISOString();
+  await mkdirFn(cartella, { recursive: true });
+  await writeFileFn(percorsoDi(cartella, id), JSON.stringify(voce, null, 2), 'utf8');
+  return voce;
+}
+
+/** Cancellazione VERA (mobile stesso: `deleteMemory`, un hard delete) — idempotente, un id già assente non è un errore. */
+export async function eliminaMemoria({ cartella, id }, deps = {}) {
+  const rmFn = deps.rmFn ?? fsp.rm;
+  const percorso = percorsoDi(cartella, id);
+  if (!percorso) return; // ⛔ 14/09: un id che non può nominare un file è già «assente» — no-op idempotente
+  await rmFn(percorso, { force: true });
+}