talos-code 0.0.1 → 0.2.0

package/vendor/harness-ui/src/research/citations.mjs

@@ -0,0 +1,142 @@
+import { talosResearchRegistrableHost } from './independence.mjs'
+
+/*
+ * PORTO FEDELE di AVM/mobile/src/lib/research/researchCitationExport.ts (118 righe, 11/09/2026).
+ *
+ * ⛔⛔ EXPORT-06 — le fonti in un formato che un gestore di bibliografie legge.
+ *
+ * Il rapporto esce già in Markdown e PDF, che sono per una persona. Chi fa un
+ * lavoro serio con delle fonti però le mette in Zotero, Mendeley o EndNote, e
+ * quei programmi parlano **BibTeX** e **RIS**. Senza, ogni riferimento va
+ * ricopiato a mano — ed è esattamente il punto in cui una bibliografia si
+ * sporca.
+ *
+ * ## ⛔ Cosa NON esce, e perché è una decisione di privacy
+ *
+ * Una citazione descrive una PAGINA, non chi l'ha letta. Da qui non escono la
+ * query che l'ha trovata, il modello che l'ha giudicata, l'identificativo della
+ * ricerca né la chat da cui viene. Un file di bibliografia finisce in una
+ * cartella condivisa, in un allegato, in un repository: è il posto meno
+ * controllato in cui un dato personale possa arrivare.
+ *
+ * ⇒ La forma in ingresso dichiara i quattro campi che servono e **basta**: ciò
+ * che il chiamante passa in più non viene nemmeno letto.
+ */
+
+/**
+ * @typedef {object} TalosResearchCitation
+ * @property {string} url
+ * @property {string} title
+ * @property {string | null} publishedAt ISO, o `null` quando la pagina non la dichiara. Non si inventa.
+ * @property {string} accessedAt Quando l'abbiamo letta: per una pagina web è il campo che conta di più.
+ */
+
+/**
+ * L'anno, solo se la data c'è ed è leggibile.
+ * @param {string | null} iso
+ * @returns {string | null}
+ */
+function anno(iso) {
+    if (!iso) return null
+    const trovato = /^(\d{4})/.exec(iso.trim())
+    return trovato ? trovato[1] : null
+}
+
+/**
+ * ⛔ Le graffe e le barre rovesce nel titolo ROMPONO il file.
+ *
+ * In BibTeX una graffa apre un gruppo: un titolo che ne contiene una spaiata fa
+ * fallire il parsing dell'intera voce — e i gestori non lo dicono, saltano la
+ * voce. Si tolgono, invece di scappare: un titolo è testo da leggere, non
+ * codice, e nessun lettore ha bisogno delle graffe originali.
+ *
+ * @param {string} testo
+ * @returns {string}
+ */
+function bibtexSicuro(testo) {
+    return testo
+        .replace(/[{}\\]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+}
+
+/**
+ * In RIS ogni riga è un campo: un a capo dentro un valore spezza il record.
+ * @param {string} testo
+ * @returns {string}
+ */
+function risSicuro(testo) {
+    return testo.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * La chiave della voce: dominio + anno, e un suffisso quando serve.
+ *
+ * ⛔ Due fonti dello stesso dominio nello stesso anno darebbero la stessa
+ * chiave, e un file con due chiavi uguali non è valido: il gestore ne butta una
+ * **in silenzio**. Chi esporta se ne accorge quando gli manca una citazione in
+ * fondo a un lavoro finito.
+ *
+ * @param {readonly TalosResearchCitation[]} citations
+ * @returns {string[]}
+ */
+function chiaviDistinte(citations) {
+    /** @type {Map<string, number>} */
+    const viste = new Map()
+    return citations.map((citation) => {
+        const host = talosResearchRegistrableHost(citation.url) ?? 'fonte'
+        const base = `${host.replace(/[^a-z0-9]/gi, '')}${anno(citation.publishedAt) ?? ''}`
+        const quante = viste.get(base) ?? 0
+        viste.set(base, quante + 1)
+        // La prima resta pulita: `example2026`, poi `example2026b`, `example2026c`.
+        return quante === 0 ? base : `${base}${String.fromCharCode(97 + quante)}`
+    })
+}
+
+/**
+ * @param {readonly TalosResearchCitation[]} citations
+ * @returns {string}
+ */
+export function talosResearchBibtex(citations) {
+    if (citations.length === 0) return ''
+    const chiavi = chiaviDistinte(citations)
+
+    return citations.map((citation, indice) => {
+        const righe = [
+            `  title = {${bibtexSicuro(citation.title)}}`,
+            `  url = {${citation.url.trim()}}`,
+            `  urldate = {${citation.accessedAt.trim()}}`,
+        ]
+        const quando = anno(citation.publishedAt)
+        // ⛔ Un anno inventato è peggio di un anno mancante: chi cita si fida.
+        if (quando) righe.splice(1, 0, `  year = {${quando}}`)
+        // `@misc` è il tipo per una risorsa online: `@article` prometterebbe una
+        // rivista, e una pagina web non lo è.
+        return `@misc{${chiavi[indice]},\n${righe.join(',\n')},\n}`
+    }).join('\n\n')
+}
+
+/**
+ * @param {readonly TalosResearchCitation[]} citations
+ * @returns {string}
+ */
+export function talosResearchRis(citations) {
+    if (citations.length === 0) return ''
+
+    return citations.map((citation) => {
+        const righe = [
+            // ELEC = risorsa elettronica, il tipo giusto per una pagina web.
+            'TY  - ELEC',
+            `TI  - ${risSicuro(citation.title)}`,
+            `UR  - ${citation.url.trim()}`,
+        ]
+        const quando = anno(citation.publishedAt)
+        if (quando) righe.push(`PY  - ${quando}`)
+        // Y2 è la data di consultazione, e RIS la vuole con le barre.
+        righe.push(`Y2  - ${citation.accessedAt.trim().replace(/-/g, '/')}`)
+        // ⛔ `ER` chiude il record e la sua riga finisce con uno spazio: è la
+        // forma che i gestori si aspettano, e senza non riconoscono la fine.
+        righe.push('ER  - ')
+        return righe.join('\n')
+    }).join('\n\n')
+}

package/vendor/harness-ui/src/research/collector.mjs

@@ -0,0 +1,275 @@
+/*
+ * PORTO FEDELE di AVM/mobile/src/lib/research/researchCollector.ts (155 righe, 11/09/2026).
+ *
+ * Raccogliere quanto vale una linea d'indagine, e tenerlo.
+ *
+ * R-3. La raccolta in sé non ha niente di notevole — cerca, leggi i primi
+ * risultati, scrivi cos'hanno detto. La decisione che conta è che il TESTO
+ * ESTRATTO SI TIENE, ed è l'unica cosa in questa fase che nessun altro fa.
+ *
+ * Ogni prodotto di ricerca sul mercato conserva link. Un link è una promessa su
+ * una pagina, e le pagine marciscono: vengono modificate, messe dietro un
+ * paywall, spostate, o semplicemente spente. Un dossier fatto di link degrada
+ * in silenzio — le citazioni sembrano a posto finché qualcuno non ne clicca una
+ * — e non si può ricontrollare affatto, perché la cosa che citava non c'è più.
+ * Tenere il passaggio rende il dossier interrogabile un anno dopo, rende
+ * possibile la ri-verifica di R12, ed è impossibile da copiare per chiunque il
+ * cui prodotto sia un elenco di URL.
+ *
+ * L'altra regola qui è quella che questo progetto ha imparato a caro prezzo:
+ * una fonte che non si è potuta leggere si REGISTRA, non si butta mai. Una
+ * raccolta che torna in silenzio con quattro fonti invece di sei sembra un tema
+ * povero invece di uno scaricamento rotto, e la differenza è tutto ciò che
+ * decide se la risposta si possa credere.
+ *
+ * ⛔ L'I/O entra da `deps` (`search`, `read`): i test usano finti, mai la rete.
+ *
+ * ## L6 (11/09/2026) — la cache e il budget entrano dalla STESSA porta
+ *
+ * Due cose nuove, e nessuna delle due è logica di raccolta: sono I/O, quindi
+ * arrivano da `deps` come `search` e `read`, e senza di loro questo file si
+ * comporta ESATTAMENTE come il porto fedele dal mobile.
+ *
+ *   - `deps.cache` (`fetch-cache.mjs`): le linee d'indagine di una ricerca
+ *     profonda partono dalla stessa domanda e aprono le stesse pagine. Con la
+ *     cache la pagina si apre una volta per corsa; senza, ogni ramo ripaga.
+ *   - `deps.budget` (`page-budget.mjs`): quanto di una pagina vede il modello,
+ *     con il resto CONSERVATO e un riferimento leggibile.
+ *
+ * ⛔ Il testo INTERO resta in `source.text`, ed è deliberato: è il dossier, ed è
+ * ciò che `talosResearchLocate` (`verification.mjs:201`) legge per decidere se
+ * un passaggio citato esiste davvero. Cercare nella finestra farebbe risultare
+ * INVENTATA una citazione onesta caduta nel mezzo tagliato — il verso peggiore.
+ * Al modello va `source.window`, che è una cosa diversa e si chiama diversamente.
+ */
+
+/**
+ * @typedef {import('./run.mjs').TalosResearchBranch} TalosResearchBranch
+ * @typedef {import('./run.mjs').TalosResearchSpend} TalosResearchSpend
+ * @typedef {import('./page-budget.mjs').TalosResearchPageReference} TalosResearchPageReference
+ */
+
+import { TALOS_RESEARCH_PAGE_BUDGET, TALOS_RESEARCH_HEAD_SHARE, talosResearchPageBudget } from './page-budget.mjs';
+
+/**
+ * @typedef {object} TalosResearchSource
+ * @property {string} url
+ * @property {string} title
+ * @property {string | null} publishedAt Quello che dice la FONTE, o null. Mai la data di oggi, mai un'ipotesi.
+ * @property {string} text
+ *   Il testo leggibile, com'era il giorno in cui è stato letto. Questo È il
+ *   dossier. Tutto quello che viene dopo — la sintesi, il controllo delle
+ *   citazioni, la ri-verifica un anno dopo — legge questo e non la rete.
+ * @property {'page' | 'snippet'} obtained
+ *   Quanta parte della fonte è davvero qui. Uno snippet è quello che il motore
+ *   di ricerca ha mostrato; una pagina è quello che la pagina ha detto.
+ *   Dichiarato perché un'affermazione sostenuta solo da uno snippet è una prova
+ *   più debole, e nasconderlo farebbe sembrare uguali le due cose.
+ * @property {string} [window]
+ *   L6. Quanto di `text` va al modello: testa + marcatore + coda quando la
+ *   pagina supera il budget, `text` identico quando non lo supera o quando
+ *   nessun budget è configurato. ⛔ Mai la fonte della verità: quella è `text`.
+ * @property {number} [omitted] Caratteri che la finestra non mostra. Contati, mai stimati.
+ * @property {boolean} [fromCache]
+ *   L6. Questa pagina NON è stata riaperta: l'aveva già pagata un altro ramo
+ *   della stessa corsa. Il registro la conta a parte da quelle aperte davvero —
+ *   «9 pagine, 4 servite dalla cache» dice una cosa che «9 pagine» non dice.
+ */
+
+/**
+ * @typedef {object} TalosResearchUnreachable
+ * @property {string} url
+ * @property {string} reason
+ */
+
+/**
+ * @typedef {object} TalosResearchCollection
+ * @property {string} branchId
+ * @property {string} query
+ * @property {readonly TalosResearchSource[]} sources
+ * @property {readonly TalosResearchUnreachable[]} unreachable Mai vuota in silenzio: quello che non si è potuto leggere ha un nome.
+ * @property {TalosResearchSpend} spend
+ *   MISURATA, non stimata. Il piano indovina; il giro conta.
+ *   ⛔ L6: è la SPESA, quindi ciò che la cache ha servito NON è qui dentro —
+ *   una pagina non riaperta non è stata pagata, e contarla renderebbe invisibile
+ *   il guadagno proprio nel numero fatto per mostrare il costo. Quanto è arrivato
+ *   gratis sta in `fromCache`, così chi legge ha tutte e due le cifre e nessuna
+ *   delle due mente.
+ * @property {{searches: number, pages: number}} fromCache
+ *   L6. Quante ricerche e quante pagine sono arrivate dalla cache della corsa.
+ *   `spend.pages + fromCache.pages` è il numero di fonti ottenute.
+ */
+
+/**
+ * @typedef {object} TalosResearchCollectorDeps
+ * @property {(query: string, maxResults: number) => Promise<readonly {url:string, title:string, snippet:string, publishedAt:string|null}[]>} search
+ * @property {(url: string) => Promise<{title:string, text:string, publishedAt:string|null} | null>} read
+ * @property {import('./fetch-cache.mjs').TalosResearchFetchCache} [cache]
+ *   L6. Se c'è, una ricerca o una pagina già viste in questa corsa non si
+ *   ripagano. Se non c'è, questo file fa esattamente quello che faceva prima.
+ * @property {string} [provider]
+ *   Chi risponde. Entra nella chiave: due fornitori non danno la stessa pagina,
+ *   e servire l'una per l'altra sarebbe una bugia silenziosa.
+ * @property {object} [budget] L6. Se assente, nessuna finestra: `window === text`.
+ * @property {number} [budget.cap] Caratteri mostrati al modello. Predefinito `TALOS_RESEARCH_PAGE_BUDGET`.
+ * @property {number} [budget.headShare] Quota in testa. Predefinita `TALOS_RESEARCH_HEAD_SHARE`.
+ * @property {number} [budget.keep]
+ *   Quanto testo si CONSERVA per fonte. Predefinito `MAX_CHARS_PER_SOURCE`
+ *   (20.000, il tetto del telefono). Sul desktop il dossier sta su disco e non
+ *   in un database solo: chi lo sa alza questo, e il budget resta sotto.
+ * @property {(url: string) => (TalosResearchPageReference | null)} [budget.reference]
+ *   Dove il chiamante ha depositato il testo intero di quella pagina, e la
+ *   chiamata esatta per sfogliarlo. ⛔ Non si inventa: chi non ha un deposito
+ *   non passa niente e il marcatore tace invece di promettere un percorso.
+ */
+
+/**
+ * Quanto si tiene di una pagina.
+ *
+ * Un articolo lungo sono decine di migliaia di caratteri e un telefono tiene
+ * l'intero dossier in un database solo. Si taglia qui invece che al momento
+ * della sintesi: quello che si tiene è quello che si potrà ri-verificare più
+ * tardi, quindi il confine appartiene a dove la prova è CONSERVATA e non a dove
+ * capita che venga letta.
+ */
+const MAX_CHARS_PER_SOURCE = 20_000;
+
+/** Quattro caratteri per token è la regola pratica consueta per la prosa. */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * @param {string} text
+ * @param {number} [tetto]
+ * @returns {string}
+ */
+function trim(text, tetto = MAX_CHARS_PER_SOURCE) {
+  const squeezed = text.replace(/\s+/g, ' ').trim();
+  return squeezed.length > tetto ? squeezed.slice(0, tetto) : squeezed;
+}
+
+/**
+ * @param {TalosResearchCollectorDeps} deps
+ * @param {TalosResearchBranch} branch
+ * @returns {Promise<TalosResearchCollection>}
+ */
+export async function talosResearchCollect(deps, branch) {
+  const wanted = Math.max(1, branch.estimate.pages);
+
+  /*
+   * ⛔ Senza cache questa è la funzione identità sul produttore: la porta è
+   * sempre la stessa, quindi non ci sono due percorsi da tenere allineati — e
+   * un ramo che esiste solo quando una dipendenza c'è è un ramo che nessun test
+   * predefinito attraversa.
+   */
+  const cache = deps.cache ?? null;
+  /**
+   * @template T
+   * @param {import('./fetch-cache.mjs').TalosResearchFetchDescriptor} descrittore
+   * @param {() => Promise<T>} produttore
+   * @returns {Promise<{value: T, fromCache: boolean}>}
+   */
+  const attorno = async (descrittore, produttore) => (
+    cache ? cache.around(descrittore, produttore) : { value: await produttore(), fromCache: false }
+  );
+
+  const conserva = Math.max(1, Math.trunc(deps.budget?.keep ?? MAX_CHARS_PER_SOURCE));
+  /** @param {string} testo @param {string} url */
+  const finestra = (testo, url) => {
+    if (!deps.budget) return { window: testo, omitted: 0 };
+    const tagliata = talosResearchPageBudget(testo, {
+      cap: deps.budget.cap ?? TALOS_RESEARCH_PAGE_BUDGET,
+      headShare: deps.budget.headShare ?? TALOS_RESEARCH_HEAD_SHARE,
+      reference: deps.budget.reference ? deps.budget.reference(url) : null,
+    });
+    return { window: tagliata.window, omitted: tagliata.omitted };
+  };
+
+  const ricerca = await attorno(
+    { kind: 'search', query: branch.question, limit: wanted, provider: deps.provider },
+    () => deps.search(branch.question, wanted),
+  );
+  const found = ricerca.value;
+
+  /** @type {TalosResearchSource[]} */
+  const sources = [];
+  /** @type {TalosResearchUnreachable[]} */
+  const unreachable = [];
+  let pages = 0;
+  let pagineDallaCache = 0;
+
+  for (const result of found) {
+    /** @type {{title:string, text:string, publishedAt:string|null} | null} */
+    let extracted = null;
+    let dallaCache = false;
+    try {
+      const letta = await attorno(
+        { kind: 'extract', url: result.url, provider: deps.provider },
+        () => deps.read(result.url),
+      );
+      extracted = letta.value;
+      dallaCache = letta.fromCache;
+    } catch (failure) {
+      unreachable.push({
+        url: result.url,
+        reason: failure instanceof Error ? failure.message : 'unknown',
+      });
+    }
+
+    if (extracted && extracted.text.trim().length > 0) {
+      if (dallaCache) pagineDallaCache += 1;
+      else pages += 1;
+      const testo = trim(extracted.text, conserva);
+      sources.push({
+        url: result.url,
+        title: extracted.title || result.title,
+        // La data della pagina vince su quella del motore di ricerca: una è
+        // l'editore che parla, l'altra è un indice che indovina.
+        publishedAt: extracted.publishedAt ?? result.publishedAt,
+        text: testo,
+        obtained: 'page',
+        ...finestra(testo, result.url),
+        fromCache: dallaCache,
+      });
+      continue;
+    }
+
+    // Si ripiega sullo snippet invece di buttare la fonte. Un risultato di
+    // ricerca che non si è potuto aprire dice comunque qualcosa, e dirlo con
+    // `obtained: 'snippet'` è onesto in un modo in cui il silenzio non è.
+    if (!extracted && unreachable.every((entry) => entry.url !== result.url)) {
+      unreachable.push({ url: result.url, reason: 'unreadable' });
+    }
+    if (result.snippet.trim().length > 0) {
+      const testo = trim(result.snippet, conserva);
+      sources.push({
+        url: result.url,
+        title: result.title,
+        publishedAt: result.publishedAt,
+        text: testo,
+        obtained: 'snippet',
+        ...finestra(testo, result.url),
+        fromCache: dallaCache,
+      });
+    }
+  }
+
+  /*
+   * ⛔ Si conta la FINESTRA, non il testo conservato: i token si pagano su ciò
+   * che arriva al modello, e conservare di più non costa un token. Senza budget
+   * la finestra È il testo, quindi questo numero è identico a prima.
+   */
+  const characters = sources.reduce((total, source) => total + (source.window ?? source.text).length, 0);
+  return {
+    branchId: branch.id,
+    query: branch.question,
+    sources,
+    unreachable,
+    spend: {
+      searches: ricerca.fromCache ? 0 : 1,
+      pages,
+      // Quello che è stato davvero assorbito, contato dal testo che è qui.
+      tokens: Math.ceil(characters / CHARS_PER_TOKEN),
+    },
+    fromCache: { searches: ricerca.fromCache ? 1 : 0, pages: pagineDallaCache },
+  };
+}

package/vendor/harness-ui/src/research/deposito-a-pezzi.mjs

@@ -0,0 +1,139 @@
+/** BC-49, contratto v1. Fonti e decisioni nel rapporto del 12/09/2026.
+ * Checkpoint applicativi completi, mai frammenti di JSON del fornitore.
+ * Il tetto riguarda gli argomenti, non promette una durata del ragionamento.
+ */
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { percorsoGiornale, scriviRapporto } from '../research-store.mjs';
+
+export const LIMITE_PARTE_RAPPORTO_BYTE = 4096;
+const MASSIMO_PARTI = 512;
+const code = new Map();
+const impronta = testo => createHash('sha256').update(testo, 'utf8').digest('hex');
+const ordinato = valore => Array.isArray(valore) ? valore.map(ordinato)
+  : valore && typeof valore === 'object' ? Object.fromEntries(Object.keys(valore).sort().map(k => [k, ordinato(valore[k])])) : valore;
+const serializza = valore => JSON.stringify(ordinato(valore));
+
+function controlla(contenuto) {
+  const { parte, testo, affermazioni, fonti } = contenuto;
+  if (!parte || !Number.isSafeInteger(parte.indice) || parte.indice < 1 || parte.indice > MASSIMO_PARTI || typeof parte.ultima !== 'boolean') {
+    return 'La parte richiede un indice intero da 1 a 512 e ultima vero o falso.';
+  }
+  if (typeof testo !== 'string' || !Array.isArray(affermazioni) || !Array.isArray(fonti)) return 'Ogni parte richiede testo e gli elenchi affermazioni e fonti, anche vuoti.';
+  if (affermazioni.some(a => !a || typeof a !== 'object' || Array.isArray(a) || typeof a.testo !== 'string' || !a.testo.trim()
+    || !((typeof a.fonte === 'string' && a.fonte.trim()) || Number.isSafeInteger(a.fonte)))) return 'Ogni affermazione richiede testo e fonte; usa il suo URL completo.';
+  if (fonti.some(f => !f || typeof f.url !== 'string' || !/^https?:\/\//i.test(f.url.trim()))) return 'Ogni fonte richiede un URL HTTP(S) completo.';
+  if (Buffer.byteLength(JSON.stringify(contenuto), 'utf8') > LIMITE_PARTE_RAPPORTO_BYTE) return `La parte supera ${LIMITE_PARTE_RAPPORTO_BYTE} byte: dividila prima di riprovare con lo stesso indice.`;
+  return null;
+}
+
+/** Replay rigoroso delle parti; gli altri eventi restano proprietà del motore L9/BC-44. */
+export function rileggiPartiRapporto(eventi) {
+  const parti = [];
+  let conclusione = null;
+  for (const evento of eventi) {
+    if (evento?.kind === 'deposit_part') {
+      const contenuto = evento.contenuto;
+      if (!contenuto || controlla(contenuto) || evento.versione !== 1 || evento.indice !== contenuto.parte.indice
+        || evento.impronta !== impronta(serializza(contenuto))) throw new Error('Integrità delle parti non verificabile: impronta o contenuto del giornale non valido.');
+      const precedente = parti[evento.indice - 1];
+      if (precedente) {
+        if (precedente.impronta !== evento.impronta) throw new Error('Integrità del giornale: due contenuti diversi per la stessa parte.');
+        continue;
+      }
+      if (evento.indice !== parti.length + 1 || parti.at(-1)?.contenuto.parte.ultima || conclusione) throw new Error('Integrità del giornale: manca una parte oppure il deposito è già chiuso.');
+      parti.push(evento);
+    } else if (evento?.kind === 'deposit_finished') {
+      if (!parti.at(-1)?.contenuto.parte.ultima || evento.ultimaImpronta !== parti.at(-1).impronta
+        || !/^[a-f0-9]{64}$/.test(evento.impronta ?? '') || !evento.risultato?.ok) throw new Error('Integrità della chiusura del deposito non verificabile.');
+      conclusione = evento;
+    }
+  }
+  return { parti, conclusione, prossimaParte: parti.length + 1 };
+}
+
+function assembla(parti) {
+  return {
+    testo: parti.map(p => p.contenuto.testo).join(''),
+    affermazioni: parti.flatMap(p => p.contenuto.affermazioni),
+    fonti: parti.flatMap(p => p.contenuto.fonti),
+  };
+}
+
+/** Un solo scrittore per ricerca nel processo che possiede la corsa; conferma dopo fsync. */
+export async function depositaParteRapporto(argomenti, { leggiGiornaleFn, accodaEventoFn, leggiRapportoFn, valida, finalizza, clock }) {
+  const { cartella, id, testo, affermazioni, fonti, parte, byteArgomenti } = argomenti;
+  const contenuto = structuredClone({ testo, affermazioni, fonti, parte });
+  const motivo = controlla(contenuto);
+  if (motivo) return { ok: false, motivo };
+  if (byteArgomenti !== undefined && (!Number.isSafeInteger(byteArgomenti) || byteArgomenti > LIMITE_PARTE_RAPPORTO_BYTE)) {
+    return { ok: false, motivo: `Gli argomenti generati superano ${LIMITE_PARTE_RAPPORTO_BYTE} byte. Dividi testo e prove; riprova lo stesso indice.` };
+  }
+  const chiave = `${resolve(cartella)}\0${id}`;
+  const precedente = code.get(chiave) ?? Promise.resolve();
+  const corrente = precedente.catch(() => {}).then(async () => {
+    const { eventi } = await leggiGiornaleFn({ cartella, id, rigoroso: true });
+    const stato = rileggiPartiRapporto(eventi);
+    const hash = impronta(serializza(contenuto));
+    const registrata = stato.parti[parte.indice - 1];
+    if (registrata && registrata.impronta !== hash) return { ok: false, motivo: `La parte ${parte.indice} è già registrata con un altro contenuto. Non riscriverla; prossima parte: ${stato.prossimaParte}.` };
+    if (!registrata && (parte.indice !== stato.prossimaParte || stato.parti.at(-1)?.contenuto.parte.ultima)) {
+      return { ok: false, motivo: `Ordine non valido: prossima parte ${stato.prossimaParte}. Una chiusura già registrata si ritenta identica.` };
+    }
+    const evento = registrata ?? {
+      kind: 'deposit_part', versione: 1, at: clock().toISOString(), indice: parte.indice,
+      impronta: hash, byte: byteArgomenti ?? Buffer.byteLength(JSON.stringify(contenuto), 'utf8'), contenuto,
+    };
+    const tutte = registrata ? stato.parti : [...stato.parti, evento];
+    const unito = parte.ultima ? assembla(tutte) : null;
+    if (unito) {
+      const controllo = valida(unito);
+      if (!controllo.ok) return controllo;
+    }
+    if (!registrata) await accodaEventoFn({ cartella, id, evento, separaRiga: true });
+    if (!parte.ultima) return {
+      ok: true, parziale: true, prossimaParte: tutte.length + 1,
+      messaggio: `Parte ${parte.indice} registrata (${evento.byte} byte). Prossima parte: ${tutte.length + 1}. Attendi questa conferma prima di proseguire; il rapporto sarà pronto soltanto dopo l'ultima parte.`,
+      contenutoRegistrato: `\n${JSON.stringify(evento)}\n`, percorsoRegistrato: percorsoGiornale(cartella, id),
+    };
+    if (stato.conclusione) {
+      const documento = await leggiRapportoFn({ cartella, id });
+      if (typeof documento !== 'string' || impronta(documento) !== stato.conclusione.impronta) throw new Error('Il rapporto concluso non coincide con l’impronta nel giornale: ripristinare il file prima di riprovare.');
+      return { ...stato.conclusione.risultato, documento, giaScritto: true };
+    }
+    const composto = await finalizza(unito);
+    if (!composto.ok) return composto;
+    await scriviRapporto({ cartella, id, testo: composto.documento });
+    const risultato = Object.fromEntries(['ok', 'affermazioni', 'fonti', 'senzaPassaggio', 'bilancio', 'giudice'].filter(k => composto[k] !== undefined).map(k => [k, composto[k]]));
+    await accodaEventoFn({ cartella, id, separaRiga: true, evento: {
+      kind: 'deposit_finished', versione: 1, at: clock().toISOString(), ultimaImpronta: hash,
+      impronta: impronta(composto.documento), byte: Buffer.byteLength(composto.documento, 'utf8'), risultato,
+    } });
+    return { ...composto, giaScritto: true };
+  });
+  code.set(chiave, corrente);
+  try { return await corrente; }
+  finally { if (code.get(chiave) === corrente) code.delete(chiave); }
+}
+
+/** La parte statica resta identica fra i giri; il progresso compare solo alla ripresa. */
+export function consegnaPartiRapporto(eventi = []) {
+  const stato = rileggiPartiRapporto(eventi);
+  const istruzioni = [
+    'Deposita il rapporto progressivamente con research_deposit dopo ogni ramo del piano, una sezione per volta, senza aspettare la fine della ricerca.',
+    'Aggiungi sempre parte:{indice:1,ultima:false}, poi aumenta indice di uno dopo ogni conferma. Questa istruzione sostituisce eventuali vecchie richieste di deposito unico.',
+    `Ogni chiamata deve contenere al massimo ${LIMITE_PARTE_RAPPORTO_BYTE} byte UTF-8 di argomenti JSON complessivi; punta a 3000 byte, circa 400 parole fra prosa e prove. Una sola chiamata di deposito per risposta: attendi la conferma prima di generare la successiva.`,
+    'testo contiene solo la sezione corrente, con gli a capo necessari: il server concatena i pezzi senza aggiungere separatori. Il primo pezzo porta il titolo; gli ultimi completano conclusioni e fonti.',
+    'Distribuisci anche affermazioni e fonti tra le parti, senza ripetere quelle già inviate; usa URL esatti in fonte. Gli elenchi possono essere vuoti. Non accumulare tutte le prove in una chiamata finale enorme.',
+    'Per chiudere usa ultima:true; se tutto è già registrato, invia testo:"", affermazioni:[], fonti:[] con il prossimo indice e ultima:true. Soltanto allora il server assembla, verifica e pubblica il rapporto.',
+    'Il messaggio finale in chat è solo una breve conferma, mai il rapporto: questa regola sostituisce anche eventuali vecchie istruzioni di scriverlo come ultimo messaggio.',
+    'Non rigenerare i pezzi confermati e non ricopiare l’intero rapporto. In caso di conferma persa, ripeti lo stesso indice con gli stessi contenuti. Scrivi rapporto e messaggi per la persona in italiano, senza nomi tecnici degli attrezzi.',
+  ];
+  if (stato.parti.length) {
+    istruzioni.push(`Parti già registrate: ${stato.parti.length}. ${stato.parti.at(-1).contenuto.parte.ultima ? 'Non aggiungere altre parti.' : `Prossima parte: ${stato.prossimaParte}.`} I contenuti confermati sono nel giornale della ricerca; leggili solo se ti servono per proseguire, senza rispedirli.`);
+    if (stato.parti.at(-1).contenuto.parte.ultima) {
+      istruzioni.push('L’ultima parte è già registrata: completa o recupera la consegna ripetendo ESATTAMENTE questa chiamata, senza altra prosa:', JSON.stringify(stato.parti.at(-1).contenuto));
+    }
+  }
+  return istruzioni.join('\n');
+}

package/vendor/harness-ui/src/research/dossier.mjs

@@ -0,0 +1,114 @@
+/*
+ * PORTO FEDELE di AVM/mobile/src/lib/research/researchDossier.ts (94 righe, 11/09/2026).
+ *
+ * ⛔ `collector.mjs` (porto di `researchCollector.ts`) lo cura un'altra sessione:
+ * qui ne servono solo i TIPI, che in JSDoc non producono nessun import a runtime.
+ * Questo file quindi gira da solo.
+ *
+ * Il dossier come UNA cosa che due lettori sanno usare.
+ *
+ * La raccolta di un ramo deve servire una persona che sfoglia la Libreria e un
+ * processo che riprende ore dopo, in un'istanza nuova, senza memoria di che
+ * cosa aveva raccolto. Le due risposte ovvie sono sbagliate entrambe. Due file
+ * — uno di prosa, uno di dati — sono due verità da tenere allineate, che è il
+ * difetto che questo progetto ha già pagato più volte. Rileggere la prosa è
+ * peggio: funziona finché qualcuno non cambia un titolo di sezione.
+ *
+ * Quindi è un documento solo: testo leggibile per la persona e per l'indice di
+ * ricerca, col record strutturato recintato in fondo. Tutti e due scritti dallo
+ * stesso oggetto nello stesso respiro, così non possono divergere, e il lettore
+ * che ha bisogno dei dati non legge mai la prosa.
+ *
+ * Un dossier senza il recinto non si indovina. Si dichiara illeggibile — un
+ * file vecchio, o uno che qualcuno ha modificato — perché una sintesi costruita
+ * su una lettura speranzosa citerebbe passaggi che non sono mai stati controllati.
+ */
+
+/**
+ * @import { TalosResearchCollection, TalosResearchSource } from './collector.mjs'
+ */
+
+const FENCE_OPEN = '```talos-research-json'
+const FENCE_CLOSE = '```'
+
+/**
+ * Che cosa porta il recinto. Con la versione, così una forma successiva si riconosce.
+ *
+ * @typedef {object} TalosResearchDossierRecord
+ * @property {1} version
+ * @property {string} branchId
+ * @property {string} query
+ * @property {readonly TalosResearchSource[]} sources
+ * @property {readonly { url: string, reason: string }[]} unreachable
+ */
+
+/**
+ * @param {TalosResearchCollection} collection
+ * @returns {string}
+ */
+export function talosResearchDossierDocument(collection) {
+    /** @type {TalosResearchDossierRecord} */
+    const record = {
+        version: 1,
+        branchId: collection.branchId,
+        query: collection.query,
+        sources: collection.sources,
+        unreachable: collection.unreachable,
+    }
+
+    const prose = [
+        `# ${collection.query}`,
+        ...collection.sources.map((source) => [
+            `## ${source.title}`,
+            source.url,
+            source.publishedAt ? `data dichiarata: ${source.publishedAt}` : 'data non dichiarata',
+            source.obtained === 'snippet' ? '(solo estratto dal motore di ricerca)' : '',
+            '',
+            source.text,
+        ].filter(Boolean).join('\n')),
+        ...(collection.unreachable.length > 0
+            ? ['## Non raggiungibili', ...collection.unreachable.map((entry) => `${entry.url} — ${entry.reason}`)]
+            : []),
+    ].join('\n\n')
+
+    // Il recinto va per ULTIMO, così un lettore che si ferma prima — un'anteprima,
+    // un estratto nei risultati di ricerca — vede la prosa e non un muro di JSON.
+    return `${prose}\n\n${FENCE_OPEN}\n${JSON.stringify(record)}\n${FENCE_CLOSE}\n`
+}
+
+/**
+ * Rilegge un dossier, o ammette di non poterlo fare.
+ *
+ * Torna `null` invece di un tentativo. Chi chiama sta per costruire un rapporto
+ * le cui citazioni verranno controllate contro questi passaggi: un dossier
+ * recuperato a metà produrrebbe affermazioni verificate contro un testo che non
+ * è quello che è stato letto.
+ *
+ * @param {string} document
+ * @returns {TalosResearchCollection | null}
+ */
+export function talosResearchParseDossier(document) {
+    const start = document.indexOf(FENCE_OPEN)
+    if (start < 0) return null
+    const from = start + FENCE_OPEN.length
+    const end = document.indexOf(FENCE_CLOSE, from)
+    if (end < 0) return null
+
+    try {
+        /** @type {TalosResearchDossierRecord} */
+        const parsed = JSON.parse(document.slice(from, end))
+        if (parsed?.version !== 1 || !Array.isArray(parsed.sources)) return null
+        return {
+            branchId: String(parsed.branchId ?? ''),
+            query: String(parsed.query ?? ''),
+            sources: parsed.sources,
+            unreachable: Array.isArray(parsed.unreachable) ? parsed.unreachable : [],
+            // La spesa non viaggia qui: sta già nel giornale, che è l'unico
+            // posto in cui si può contare. Una seconda copia prima o poi
+            // verrebbe sommata alla prima.
+            spend: { searches: 0, pages: 0, tokens: 0 },
+        }
+    } catch {
+        return null
+    }
+}