@sylad/cadence 1.9.0 → 1.11.0

package/dist/ref/analyse.js

@@ -0,0 +1,220 @@
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACKAGE_ROOT } from '../orchestrate/snapshot.js';
+import { RafError } from '../plan.js';
+import { add } from './add.js';
+import { checkInventaire, readInventaire } from './check.js';
+import { assembler, parseSeuil, reconcilier } from './diff.js';
+import { troisiemeRegard } from './regard.js';
+import { sessionDeRef } from './session.js';
+/** Plafond déclaré d'une lecture : au plus 20 pages rendues lues d'un coup (design §5, « Taille »). Au-delà, `--sections` en choisit moins. */
+export const LECTURE_PAGES_MAX = 20;
+export const ANALYSE_MODELS = ['sonnet', 'opus', 'haiku'];
+/** Sortie structurée de la session : ce que l'agent dit de sa lecture ; le programme ne s'y fie pas, il relit le fichier. */
+export const ANALYSE_SCHEMA = {
+    type: 'object',
+    properties: {
+        resume: { type: 'string', description: 'Two sentences: what the document is and what the reading holds.' },
+        questions: { type: 'array', items: { type: 'string' }, description: 'What a human must settle: a contradiction, an element that could not be read.' },
+    },
+    required: ['resume', 'questions'],
+    additionalProperties: false,
+};
+/** Consigne de la lecture : tout ce que l'agent a besoin de savoir, rien de l'attendu d'un corpus, rien d'une autre lecture. */
+function brief(o) {
+    const cadence = `node ${join(PACKAGE_ROOT, 'bin', 'cadence.js')}`;
+    const config = `--config ${o.configPath}`;
+    return [
+        `Lis le document de référence « ${o.slug} » et écris sa lecture.`,
+        '',
+        `Dossier du document : ${o.docDir} (document.json : texte positionné, images, index des figures et passages qui les citent).`,
+        `Pages rendues à 200 dpi (${o.pages.length}) :`,
+        ...o.pages.map((n) => `- ${join(o.docDir, 'pages', `page-${n}.png`)}`),
+        '',
+        `Modèle du format : ${join(PACKAGE_ROOT, 'templates', 'inventaire.json')} (genre « lecture », sans la clé pages ; slug et sha256 recopiés de document.json).`,
+        `Lecture à écrire : ${o.file}`,
+        '',
+        'Commandes :',
+        `- mesurer une zone (pixels de la page rendue) : ${cadence} ref measure ${o.slug} <page> <page | x,y | x,y,l,h> --quoi couleurs|contraste|boites|texte ${config}`,
+        `- valider la lecture, jusqu'à ce qu'elle passe : ${cadence} ref check ${o.file}`,
+        '',
+        `Ne lis que ce dossier, le modèle et les pages ci-dessus, et aucun autre fichier de ${join(o.docDir, 'lectures')} que le tien : une autre lecture du même document peut s'y trouver, la tienne doit être la seule que tu connais ; n'écris que ${o.file}. Les jetons ne sont pas à écrire : le programme les compte.`,
+    ].join('\n');
+}
+/** « 1 page lue », « 3 pages lues ». */
+const pagesLues = (n) => `${n} page${n > 1 ? 's' : ''} lue${n > 1 ? 's' : ''}`;
+/** Les écarts d'une lecture au-delà du schéma : le genre, et le document lu (jamais une mesure sur deux versions mêlées). */
+function ecartsDeLecture(lecture, doc) {
+    const l = lecture;
+    const out = [];
+    if (l.genre !== 'lecture')
+        out.push('genre : « lecture » attendu (une lecture, pas un inventaire)');
+    if (l.document?.slug !== doc.slug)
+        out.push(`document.slug : « ${String(l.document?.slug)} » n'est pas le document lu (${doc.slug})`);
+    if (l.document?.sha256 !== doc.sha256)
+        out.push(`document.sha256 : l'empreinte n'est pas celle du document lu (${doc.sha256.slice(0, 12)}…)`);
+    return out;
+}
+/** Une lecture : une session neuve de `reference-analyst` qui écrit `lectures/<nom>.json`, relue par le programme (ref check, genre, document) ; les jetons de la session y sont posés dans `usage`. */
+async function lireUne(c, nom, model) {
+    const file = join(c.docDir, 'lectures', `${nom}.json`);
+    rmSync(file, { force: true }); // une lecture d'un passage précédent ne passe jamais pour celle de celui-ci
+    const r = await sessionDeRef({
+        agent: 'reference-analyst',
+        brief: brief({ slug: c.slug, docDir: c.docDir, pages: c.pages, file, configPath: c.o.configPath }),
+        model,
+        schema: ANALYSE_SCHEMA,
+        slug: c.slug,
+        docDir: c.docDir,
+        configPath: c.o.configPath,
+        claudeHome: c.o.claudeHome,
+        claude: c.o.claude,
+        agents: c.o.agents,
+        onRelaunch: () => rmSync(file, { force: true }), // la lecture à moitié écrite de la session coupée ne passe pas pour celle de la neuve
+        echec: 'la session de lecture a échoué',
+    });
+    if (r.kind === 'quota')
+        return r;
+    if (!existsSync(file))
+        return { kind: 'refus', problems: [`aucune lecture écrite : ${file}`] };
+    let lecture;
+    try {
+        lecture = readInventaire(file);
+    }
+    catch (e) {
+        return { kind: 'refus', problems: [e.message] };
+    }
+    const schema = checkInventaire(lecture);
+    const problems = schema.length > 0 ? schema : ecartsDeLecture(lecture, c.doc);
+    if (problems.length > 0)
+        return { kind: 'refus', problems };
+    const usage = { tokens: r.tokens, modele: model, session: r.session };
+    lecture.usage = usage;
+    writeFileSync(file, `${JSON.stringify(lecture, null, 2)}\n`);
+    const structured = r.structured;
+    return { kind: 'ok', lecture, file, usage, questions: Array.isArray(structured?.questions) ? structured.questions.map(String) : [] };
+}
+const confiancesDe = (lecture) => ['mesure', 'lu', 'incertain'].map((c) => [c, lecture.elements.filter((e) => e.confiance === c).length]).filter(([, n]) => n > 0).map(([c, n]) => `${c} : ${n}`).join(', ');
+/**
+ * `cadence ref analyse` : la chaîne — add, puis UNE lecture (une session de l'agent `reference-analyst`, `lectures/a.json`) ; avec `--double`, deux lectures
+ * indépendantes (A et B, modèles possiblement différents), `ref diff` (réconciliation par le programme), le troisième regard sur ce qu'une seule lecture
+ * porte, l'inventaire écrit avec les jetons posés dans `usage` (la double lecture n'a pas montré de gain : c'est une option, pas le défaut). Rend le code de sortie : 0 fait, 1 lecture refusée ou trop d'éléments non
+ * appariés ou aucun élément gardé par le troisième regard, 3 quota ; une session en échec ou un refus d'entrée (modèle, plafond, aucune page) lève une `RafError` (code 2).
+ */
+export async function analyse(o) {
+    const model = (o.model ?? 'sonnet');
+    const modelB = (o.modelB ?? 'opus');
+    if (!ANALYSE_MODELS.includes(model))
+        throw new RafError(`ref analyse : --model invalide : « ${o.model} » (attendu : ${ANALYSE_MODELS.join(', ')})`);
+    if (!ANALYSE_MODELS.includes(modelB))
+        throw new RafError(`ref analyse : --model-b invalide : « ${o.modelB} » (attendu : ${ANALYSE_MODELS.join(', ')})`);
+    if (!o.double && o.modelB !== undefined)
+        throw new RafError('ref analyse : --model-b n\'a de sens qu\'avec --double (une seule lecture, pas de lecture B)');
+    if (!o.double && o.seuil !== undefined)
+        throw new RafError('ref analyse : --seuil n\'a de sens qu\'avec --double (une seule lecture, rien à réconcilier)');
+    const seuil = parseSeuil(o.seuil, 'ref analyse');
+    const { slug, docDir, doc, lues: pages } = add({ document: o.document, slug: o.slug, sections: o.sections, env: o.env, cwd: o.cwd, refsDir: o.refsDir, now: o.now, out: o.out });
+    const sections = `\n  choisir les pages à lire : cadence ref analyse ${o.document} --slug ${slug} --sections 3-12`;
+    if (pages.length === 0)
+        throw new RafError(`ref analyse : aucune page rendue : rien à lire${sections}`);
+    if (pages.length > LECTURE_PAGES_MAX)
+        throw new RafError(`ref analyse : ${pages.length} pages ${o.sections === undefined ? 'rendues' : 'à lire (--sections et les figures qu\'elles citent)'}, plafond d'une lecture : ${LECTURE_PAGES_MAX} pages${sections}`);
+    const c = { o, slug, docDir, doc, pages };
+    const refuse = (problems, prefixe = '') => {
+        for (const p of problems)
+            o.out(`✗ ${prefixe}${p}`);
+        o.out(`${problems.length} écart(s)`);
+        return 1;
+    };
+    if (!o.double) {
+        // les fichiers d'une double lecture précédente ne passent pas pour ceux de ce passage : leur `usage.lectures.a` ne serait plus celui de `a.json`
+        rmSync(join(docDir, 'lectures', 'b.json'), { force: true });
+        rmSync(join(docDir, 'inventaire.json'), { force: true });
+        const r = await lireUne(c, 'a', model);
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint, aucune lecture écrite : ${r.message}`);
+            return 3;
+        }
+        if (r.kind === 'refus')
+            return refuse(r.problems);
+        o.out(`${slug} : lecture unique (${model}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`lecture : ${r.file}`);
+        o.out(`éléments : ${r.lecture.elements.length} (${confiancesDe(r.lecture)})`);
+        o.out(`tokens : ${r.usage.tokens} (${Math.round(r.usage.tokens / pages.length)} par page, ${pagesLues(pages.length)})`);
+        for (const q of r.questions)
+            o.out(`question : ${q}`);
+        return 0;
+    }
+    const inventaire = join(docDir, 'inventaire.json');
+    rmSync(inventaire, { force: true }); // l'inventaire d'un passage précédent ne passe jamais pour celui de celui-ci
+    // deux sessions qui ne se voient pas : lancées ensemble, chacune écrit sa lecture ; un échec n'interrompt pas l'autre
+    const [ra, rb] = await Promise.allSettled([lireUne(c, 'a', model), lireUne(c, 'b', modelB)]);
+    for (const r of [ra, rb])
+        if (r.status === 'rejected')
+            throw r.reason;
+    const [a, b] = [ra, rb].map((r) => r.value);
+    const lues = [['A', a], ['B', b]];
+    for (const [nom, r] of lues) {
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint (lecture ${nom}), aucune réconciliation : ${r.message}`);
+            return 3;
+        }
+    }
+    const refus = lues.flatMap(([nom, r]) => (r.kind === 'refus' ? r.problems.map((p) => `lecture ${nom} : ${p}`) : []));
+    if (refus.length > 0)
+        return refuse(refus);
+    const [la, lb] = [a, b];
+    const rec = reconcilier(la.lecture, lb.lecture, seuil);
+    const pct = (x) => `${Number((x * 100).toFixed(1))} %`;
+    const compteRec = `concordants ${rec.concordants} · divergents ${rec.divergents} · seuls ${rec.seuls} · silences ${rec.silences}`;
+    if (rec.refuse) {
+        o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`réconciliation : ${compteRec} — non appariés ${pct(rec.ratio)} (seuil ${pct(seuil)})`);
+        o.out(`plus de ${pct(seuil)} d'éléments non appariés (${rec.nonApparies} sur ${rec.concordants + rec.divergents + rec.seuls}) : les deux lectures ne décrivent pas le même document — question au lead, aucune réconciliation (les lectures restent dans ${join(docDir, 'lectures')}, \`cadence ref diff\` les compare)`);
+        return 1;
+    }
+    const seuls = rec.items.filter((i) => i.statut === 'seul');
+    let regard;
+    if (seuls.length > 0) {
+        const r = await troisiemeRegard({ seuls, model, slug, docDir, configPath: o.configPath, claudeHome: o.claudeHome, claude: o.claude, agents: o.agents });
+        if (r.kind === 'quota') {
+            o.err(`ref analyse : quota atteint pendant le troisième regard, aucun inventaire écrit (les lectures A et B sont gardées) : ${r.message}`);
+            return 3;
+        }
+        seuls.forEach((item, i) => (item.decision = r.decisions[i]));
+        regard = r;
+    }
+    const inv = assembler(la.lecture, lb.lecture, rec, regard !== undefined);
+    if (inv.elements.length === 0) {
+        // tout ce que les lectures portent n'était porté que par une seule d'entre elles et le troisième regard l'a écarté : rien à écrire, ce n'est pas un défaut de cadence
+        o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+        o.out(`réconciliation : ${compteRec}`);
+        o.out(`le troisième regard a écarté tous les éléments : aucun inventaire — question au lead (les lectures restent dans ${join(docDir, 'lectures')}, \`cadence ref diff\` les compare)`);
+        return 1;
+    }
+    // la réconciliation ne produit que des éléments déjà valides : un écart ici est un défaut de cadence, jamais une lecture à refuser
+    const problems = checkInventaire(inv);
+    if (problems.length > 0)
+        throw new RafError(`ref analyse : l'inventaire réconcilié est invalide (défaut de cadence) : ${problems[0]}`);
+    const tokens = la.usage.tokens + lb.usage.tokens + (regard?.tokens ?? 0);
+    inv.usage = {
+        tokens,
+        lectures: { a: { tokens: la.usage.tokens, modele: model }, b: { tokens: lb.usage.tokens, modele: modelB }, ...(regard ? { regard: { tokens: regard.tokens, modele: model } } : {}) },
+    };
+    const verdicts = seuls.flatMap((item) => (item.decision ? [{ lecture: item.lecture, id: item.element.id, verdict: item.decision.verdict, raison: item.decision.raison }] : []));
+    inv.reconciliation = { concordants: rec.concordants, divergents: rec.divergents, seuls: rec.seuls, silences: rec.silences, non_apparies: rec.ratio, regard: verdicts };
+    writeFileSync(inventaire, `${JSON.stringify(inv, null, 2)}\n`);
+    const confirmes = verdicts.filter((v) => v.verdict === 'confirme').length;
+    const ecartes = verdicts.length - confirmes;
+    o.out(`${slug} : double lecture (A ${model}, B ${modelB}) — ${pagesLues(pages.length)} (plafond d'une lecture : ${LECTURE_PAGES_MAX})`);
+    o.out(`lectures : ${la.file}, ${lb.file}`);
+    o.out(`réconciliation : ${compteRec} — non appariés ${rec.ratio === null ? 'n/a' : pct(rec.ratio)} (seuil ${pct(seuil)})`);
+    if (regard)
+        o.out(`troisième regard (${model}) : ${confirmes} confirmé${confirmes > 1 ? 's' : ''}, ${ecartes} écarté${ecartes > 1 ? 's' : ''}, ${seuls.length - verdicts.length} sans réponse`);
+    o.out(`inventaire : ${inventaire}`);
+    o.out(`éléments : ${inv.elements.length} (${confiancesDe(inv)})`);
+    o.out(`tokens : ${tokens} (${Math.round(tokens / pages.length)} par page, ${pagesLues(pages.length)}) — A : ${la.usage.tokens}, B : ${lb.usage.tokens}${regard ? `, troisième regard : ${regard.tokens}` : ''}`);
+    for (const q of new Set([...la.questions, ...lb.questions, ...(regard?.questions ?? [])]))
+        o.out(`question : ${q}`);
+    return 0;
+}

package/dist/ref/command.js

@@ -1,16 +1,23 @@
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { RafError } from '../plan.js';
+import { AGENTS_DIR } from '../skills.js';
+import { realClaude, readAgents } from '../orchestrate/launch.js';
 import { add } from './add.js';
+import { analyse } from './analyse.js';
 import { checkInventaire, readInventaire, summaryInventaire } from './check.js';
 import { buildCorpus } from './corpus.js';
+import { diffLectures } from './diff.js';
 import { chargerPlaywright, lancer, rendre } from './corpus-render.js';
 import { evaluer, formatEvaluation } from './evaluate.js';
 import { measure } from './measure.js';
 import { referencesDir } from './store.js';
 const USAGE_ADD = 'usage : cadence ref add <document.pdf> [--sections 3-5,9] [--slug nom]';
+const USAGE_ANALYSE = 'usage : cadence ref analyse <document.pdf> [--sections 3-5,9] [--slug nom] [--model sonnet|opus|haiku] [--model-b sonnet|opus|haiku] [--seuil 30] [--double]';
 const USAGE_CHECK = 'usage : cadence ref check <inventaire.json | lecture.json>';
+const USAGE_DIFF = 'usage : cadence ref diff <lecture-a.json> <lecture-b.json> [--out inventaire.json] [--seuil 30]';
 const USAGE_EVAL = 'usage : cadence ref eval <attendu.json | dossier> <lecture.json | dossier> [--json]';
 const USAGE_CORPUS = 'usage : cadence ref corpus <dossier> [--sans-rendu]';
 const USAGE_MEASURE = 'usage : cadence ref measure <slug> <page> <page | x,y | x,y,l,h> [--quoi couleurs|contraste|boites|texte] [--largeur 1440] [--json]';
@@ -23,6 +30,10 @@ export function refCommand(rest, values, root, io) {
         add({ document: args[0], slug: values.slug, sections: values.sections, env: io.env, cwd: io.cwd, refsDir, now: io.now(), out: io.out });
         return 0;
     }
+    if (verb === 'analyse' && args.length === 1) {
+        const claude = realClaude(io.env.CADENCE_CLAUDE_BIN || 'claude', io.env);
+        return analyse({ document: args[0], slug: values.slug, sections: values.sections, model: values.model, modelB: values['model-b'], double: values.double === true, seuil: values.seuil, env: io.env, cwd: io.cwd, refsDir, configPath, claudeHome: io.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), now: io.now(), out: io.out, err: io.err, claude, agents: readAgents(AGENTS_DIR) });
+    }
     if (verb === 'measure' && args.length === 3) {
         measure({ slug: args[0], page: args[1], zone: args[2], quoi: values.quoi, largeur: values.largeur, env: io.env, refsDir, json: values.json === true, out: io.out });
         return 0;
@@ -40,6 +51,9 @@ export function refCommand(rest, values, root, io) {
         io.out(summaryInventaire(inventaire));
         return 0;
     }
+    if (verb === 'diff' && args.length === 2) {
+        return diffLectures({ a: resolve(io.cwd, args[0]), b: resolve(io.cwd, args[1]), seuil: values.seuil, out: values.out === undefined ? undefined : resolve(io.cwd, values.out), log: io.out });
+    }
     if (verb === 'eval' && args.length === 2) {
         const ev = evaluer(resolve(io.cwd, args[0]), resolve(io.cwd, args[1]));
         if (values.json === true)
@@ -52,7 +66,7 @@ export function refCommand(rest, values, root, io) {
     if (verb === 'corpus' && args.length === 1)
         return corpus(resolve(io.cwd, args[0]), values['sans-rendu'] === true, io);
     const others = (u) => u.replace('usage : ', '');
-    throw new RafError(verb === 'add' ? USAGE_ADD : verb === 'measure' ? USAGE_MEASURE : verb === 'check' ? USAGE_CHECK : verb === 'eval' ? USAGE_EVAL : verb === 'corpus' ? USAGE_CORPUS : `${USAGE_ADD}\n       ${others(USAGE_MEASURE)}\n       ${others(USAGE_CHECK)}\n       ${others(USAGE_EVAL)}\n       ${others(USAGE_CORPUS)}`);
+    throw new RafError(verb === 'add' ? USAGE_ADD : verb === 'analyse' ? USAGE_ANALYSE : verb === 'measure' ? USAGE_MEASURE : verb === 'check' ? USAGE_CHECK : verb === 'diff' ? USAGE_DIFF : verb === 'eval' ? USAGE_EVAL : verb === 'corpus' ? USAGE_CORPUS : `${USAGE_ADD}\n       ${others(USAGE_ANALYSE)}\n       ${others(USAGE_MEASURE)}\n       ${others(USAGE_CHECK)}\n       ${others(USAGE_DIFF)}\n       ${others(USAGE_EVAL)}\n       ${others(USAGE_CORPUS)}`);
 }
 /** `ref corpus <dossier>` : un sous-dossier par piège (document.html, attendu.json, puis document.pdf et page-<n>.png sauf --sans-rendu). */
 async function corpus(dossier, sansRendu, io) {

package/dist/ref/diff.js

@@ -0,0 +1,262 @@
+import { writeFileSync } from 'node:fs';
+import { RafError } from '../plan.js';
+import { TYPES, checkInventaire, readInventaire } from './check.js';
+import { affirmation, identite } from './evaluate.js';
+/** Au-delà de cette part d'éléments non appariés, les deux lectures ne décrivent pas le même document : pas de réconciliation (design §3, hypothèse H3). */
+export const SEUIL_NON_APPARIES = 0.3;
+/** Recouvrement minimal (intersection sur union) de deux zones du même type et de la même page pour que deux lectures parlent du même élément lu autrement. */
+const RECOUVREMENT_MIN = 0.5;
+const zoneOf = (e) => e.source?.zone;
+/** Intersection sur union de deux zones ; 0 quand l'une manque. */
+function recouvrement(a, b) {
+    const p = zoneOf(a);
+    const q = zoneOf(b);
+    if (!p || !q)
+        return 0;
+    const l = Math.min(p.x + p.l, q.x + q.l) - Math.max(p.x, q.x);
+    const h = Math.min(p.y + p.h, q.y + q.h) - Math.max(p.y, q.y);
+    if (l <= 0 || h <= 0)
+        return 0;
+    const inter = l * h;
+    return inter / (p.l * p.h + q.l * q.h - inter);
+}
+const SKIP = new Set(['id', 'type', 'source', 'confiance', 'cause', 'ocr', 'citations', 'ecran', 'cible', 'couvre', 'usage']);
+const show = (v) => {
+    const s = v === undefined ? 'absent' : typeof v === 'string' ? v : JSON.stringify(v);
+    return s.length > 60 ? `${s.slice(0, 59)}…` : s;
+};
+/** Les champs qui diffèrent, « champ : A « … » ≠ B « … » » : les ids et les renvois sont numérotés par chaque lecture, ils ne comptent pas. */
+function detailDivergence(a, b) {
+    const out = [];
+    for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+        if (SKIP.has(k) || JSON.stringify(a[k]) === JSON.stringify(b[k]))
+            continue;
+        out.push(`${k} : A « ${show(a[k])} » ≠ B « ${show(b[k])} »`);
+    }
+    return out.length > 0 ? out.join(' ; ') : 'affirmations différentes';
+}
+/**
+ * Apparie deux lectures du même document, par type, page, identité (ce qui désigne l'élément, comme `ref eval`) et recouvrement de zone :
+ * concordant (même identité, même affirmation), divergent (même identité et affirmation différente, ou même zone et identité différente), seul.
+ * Les silences sont réunis, une même question une seule fois. `seuil` : part de non appariés au-delà de laquelle `refuse` est vrai.
+ */
+export function reconcilier(a, b, seuil = SEUIL_NON_APPARIES) {
+    const parIdA = new Map(a.elements.map((e) => [e.id, e]));
+    const parIdB = new Map(b.elements.map((e) => [e.id, e]));
+    const cle = (e, par) => `${e.source?.page}\u0000${identite(e, par)}`;
+    const items = new Map();
+    const pairedB = new Set();
+    for (const type of TYPES.filter((t) => t !== 'silence')) {
+        const as = a.elements.filter((e) => e.type === type);
+        const bs = b.elements.filter((e) => e.type === type);
+        const libresB = () => bs.filter((e) => !pairedB.has(e));
+        const lier = (ea, eb, statut) => {
+            pairedB.add(eb);
+            items.set(ea, { statut, element: ea, a: ea, b: eb, ...(statut === 'divergent' ? { detail: detailDivergence(ea, eb) } : {}) });
+        };
+        const meilleur = (ea, candidats) => candidats.reduce((best, c) => (best === undefined || recouvrement(ea, c) > recouvrement(ea, best) ? c : best), undefined);
+        // 1. même identité et même affirmation ; 2. même identité, affirmation différente ; 3. identité différente mais même zone
+        for (const ea of as) {
+            const eb = meilleur(ea, libresB().filter((c) => cle(c, parIdB) === cle(ea, parIdA) && affirmation(c, parIdB) === affirmation(ea, parIdA)));
+            if (eb)
+                lier(ea, eb, 'concordant');
+        }
+        for (const ea of as.filter((e) => !items.has(e))) {
+            const eb = meilleur(ea, libresB().filter((c) => cle(c, parIdB) === cle(ea, parIdA)));
+            if (eb)
+                lier(ea, eb, 'divergent');
+        }
+        for (const ea of as.filter((e) => !items.has(e))) {
+            const eb = meilleur(ea, libresB().filter((c) => c.source?.page === ea.source?.page && recouvrement(ea, c) >= RECOUVREMENT_MIN));
+            if (eb)
+                lier(ea, eb, 'divergent');
+        }
+        for (const ea of as.filter((e) => !items.has(e)))
+            items.set(ea, { statut: 'seul', element: ea, a: ea, lecture: 'a' });
+    }
+    // l'ordre de l'inventaire : la lecture A dans son ordre, puis ce que B seule porte dans son ordre
+    const ordered = [];
+    for (const e of a.elements)
+        if (e.type !== 'silence')
+            ordered.push(items.get(e));
+    for (const e of b.elements)
+        if (e.type !== 'silence' && !pairedB.has(e))
+            ordered.push({ statut: 'seul', element: e, b: e, lecture: 'b' });
+    const vues = new Map();
+    for (const [e, lecture] of [...a.elements.map((e) => [e, 'a']), ...b.elements.map((e) => [e, 'b'])]) {
+        if (e.type !== 'silence')
+            continue;
+        const k = identite(e, new Map());
+        const deja = vues.get(k);
+        if (deja) {
+            (deja.alias ??= []).push(`${lecture}:${e.id}`); // un statut peut couvrir ce silence-ci : son renvoi suit le silence réuni
+            continue;
+        }
+        const item = { statut: 'silence', element: e, ...(lecture === 'a' ? { a: e } : { b: e }) };
+        vues.set(k, item);
+        ordered.push(item);
+    }
+    const compte = (s) => ordered.filter((i) => i.statut === s).length;
+    const concordants = compte('concordant');
+    const divergents = compte('divergent');
+    const seuls = compte('seul');
+    const total = concordants + divergents + seuls;
+    const ratio = total === 0 ? null : seuls / total;
+    return { items: ordered, concordants, divergents, seuls, silences: compte('silence'), nonApparies: seuls, ratio, refuse: ratio !== null && ratio > seuil };
+}
+/** Les renvois d'un élément à d'autres éléments de sa lecture : (champ, ids). `ecran` et `cible` sont obligatoires, `couvre` se réduit. */
+const renvois = (e) => (e.type === 'composant' ? [e.ecran] : e.type === 'etat' ? [e.cible] : e.type === 'statut' ? e.couvre : []);
+const lectureLabel = (l) => l.toUpperCase();
+/** La confiance d'un élément concordant : un doute d'une lecture est un doute ; sinon `mesure` si l'une des deux a mesuré, `lu` sinon. */
+function confianceConcordant(ea, eb) {
+    if (ea.confiance === 'incertain' || eb.confiance === 'incertain') {
+        const causes = [ea, eb].filter((e) => e.confiance === 'incertain').map((e) => e.cause);
+        return { confiance: 'incertain', cause: [...new Set(causes)].join(' ; ') };
+    }
+    return { confiance: ea.confiance === 'mesure' || eb.confiance === 'mesure' ? 'mesure' : 'lu' };
+}
+/**
+ * L'inventaire réconcilié (genre « inventaire »), ids renumérotés `<slug>#<type>-<n>` et renvois suivis. Un divergent est `incertain` avec les deux
+ * versions ; un seul écarté par le troisième regard disparaît (avec ce qui ne tient plus sans lui), un seul confirmé garde sa confiance (un doute
+ * reste un doute), un seul sans décision reste `incertain` : `regard` dit si le troisième regard a eu lieu (sa cause le dit).
+ * Un élément apparié tient tant que l'une de ses deux versions renvoie à des éléments gardés (la lecture A d'abord) : quand l'autre version renvoyait à un
+ * élément écarté, il est gardé, rattaché d'après la version qui tient, et `incertain` avec la cause du rattachement ; il disparaît quand aucune ne tient.
+ */
+export function assembler(a, b, rec, regard = false) {
+    const entrees = rec.items.map((item) => ({ item, supprimee: item.statut === 'seul' && item.decision?.verdict === 'ecarte' }));
+    const proprietaire = new Map();
+    for (const en of entrees) {
+        if (en.item.a)
+            proprietaire.set(`a:${en.item.a.id}`, en);
+        if (en.item.b)
+            proprietaire.set(`b:${en.item.b.id}`, en);
+        for (const k of en.item.alias ?? [])
+            proprietaire.set(k, en);
+    }
+    const versionsDe = (en) => ['a', 'b'].filter((v) => en.item[v] !== undefined);
+    const cible = (v, id) => proprietaire.get(`${v}:${id}`);
+    const vivant = (v, id) => {
+        const t = cible(v, id);
+        return t !== undefined && !t.supprimee;
+    };
+    /** Une version tient quand ses renvois tiennent : tous pour un composant ou un état, au moins un pour un statut. */
+    const tient = (en, v) => {
+        const element = en.item[v];
+        const ids = renvois(element);
+        const vivants = ids.filter((id) => vivant(v, id)).length;
+        return ids.length === 0 || (element.type === 'statut' ? vivants > 0 : vivants === ids.length);
+    };
+    // ce qui renvoie à un élément écarté ne tient plus : un point fixe, un écarté pouvant en entraîner d'autres. Un élément apparié tient dès que l'une de
+    // ses deux versions tient (la lecture A d'abord) : la lecture B peut le rattacher à un écran conservé quand A le rattache à un écran écarté.
+    for (let change = true; change;) {
+        change = false;
+        for (const en of entrees) {
+            if (en.supprimee)
+                continue;
+            const v = versionsDe(en).find((x) => tient(en, x));
+            if (v === undefined) {
+                en.supprimee = true;
+                change = true;
+            }
+            else
+                en.version = v;
+        }
+    }
+    const compteur = new Map();
+    const nouvelId = new Map();
+    for (const en of entrees) {
+        if (en.supprimee)
+            continue;
+        const type = en.item.element.type;
+        const n = (compteur.get(type) ?? 0) + 1;
+        compteur.set(type, n);
+        nouvelId.set(en, `${a.document.slug}#${type}-${n}`);
+    }
+    const elements = entrees.filter((en) => !en.supprimee).map((en) => {
+        const { item } = en;
+        const v = en.version;
+        const e = { ...item.element, id: nouvelId.get(en) };
+        const id = (ancien) => nouvelId.get(cible(v, ancien));
+        // les renvois sont ceux de la version qui tient (pour un élément apparié, parfois celle de la lecture B)
+        const source = item[v];
+        if (e.type === 'composant')
+            e.ecran = id(source.ecran);
+        if (e.type === 'etat')
+            e.cible = id(source.cible);
+        if (e.type === 'statut')
+            e.couvre = source.couvre.filter((x) => vivant(v, x)).map(id);
+        const doute = (cause) => {
+            e.confiance = 'incertain';
+            e.cause = cause;
+        };
+        if (item.statut === 'concordant') {
+            const { confiance, cause } = confianceConcordant(item.a, item.b);
+            e.confiance = confiance;
+            if (cause === undefined)
+                delete e.cause;
+            else
+                e.cause = cause;
+        }
+        else if (item.statut === 'divergent') {
+            doute(`lectures divergentes — ${item.detail}`);
+        }
+        else if (item.statut === 'seul' && item.decision?.verdict !== 'confirme') {
+            const base = `lu dans la lecture ${lectureLabel(item.lecture)} seulement, troisième regard ${regard ? 'sans réponse' : 'non fait'}`;
+            doute(item.element.confiance === 'incertain' ? `${base} ; ${item.element.cause}` : base);
+        }
+        // les deux lectures ne le rattachent plus au même élément : l'une renvoyait à un élément écarté par le troisième regard, l'élément est gardé
+        // par l'autre (il est lu, ou mesuré, par les deux) mais son rattachement n'est plus qu'une lecture : un doute, avec sa cause
+        const autre = v === 'a' ? 'b' : 'a';
+        if (item.a && item.b && !tient(en, autre)) {
+            const note = `rattachement : la lecture ${lectureLabel(autre)} le rattachait à un élément écarté par le troisième regard, rattaché d'après la lecture ${lectureLabel(v)}`;
+            doute(e.confiance === 'incertain' ? `${e.cause} ; ${note}` : note);
+        }
+        return e;
+    });
+    return { version: 1, genre: 'inventaire', document: { slug: a.document.slug, sha256: a.document.sha256 }, elements };
+}
+function lireLecture(path) {
+    const doc = readInventaire(path);
+    const problems = checkInventaire(doc);
+    if (problems.length > 0)
+        throw new RafError(`ref diff : ${path} n'est pas valide (${problems.length} écart(s), voir cadence ref check) : ${problems[0]}`);
+    if (doc.genre !== 'lecture')
+        throw new RafError(`ref diff : ${path} doit être une lecture, pas un « ${doc.genre} »`);
+    return doc;
+}
+/** `--seuil` : une part en pour cent (0 à 100) rendue en fraction ; absent, le seuil de la conception. */
+export function parseSeuil(text, commande) {
+    if (text === undefined)
+        return SEUIL_NON_APPARIES;
+    if (!/^\d+(\.\d+)?$/.test(text) || Number(text) > 100)
+        throw new RafError(`${commande} : --seuil invalide : « ${text} » (une part en pour cent, de 0 à 100)`);
+    return Number(text) / 100;
+}
+/** `ref diff <a> <b> [--out inventaire.json] [--seuil 30]` : 0 réconcilié, 1 trop d'éléments non appariés (rien d'écrit), 2 fichier ou appel refusé. */
+export function diffLectures(o) {
+    const seuil = parseSeuil(o.seuil, 'ref diff');
+    const a = lireLecture(o.a);
+    const b = lireLecture(o.b);
+    if (a.document.slug !== b.document.slug)
+        throw new RafError(`ref diff : les deux lectures ne sont pas du même document : slug ${a.document.slug} et ${b.document.slug}`);
+    if (a.document.sha256 !== b.document.sha256)
+        throw new RafError(`ref diff : l'empreinte des deux lectures diffère pour ${a.document.slug} : pas la même version du document (jamais deux versions mêlées)`);
+    const rec = reconcilier(a, b, seuil);
+    const sa = rec.items.filter((i) => i.statut === 'seul' && i.lecture === 'a').length;
+    const pct = (x) => `${Number((x * 100).toFixed(1))} %`;
+    o.log(`concordants : ${rec.concordants} · divergents : ${rec.divergents} · seuls : ${rec.seuls} (A : ${sa}, B : ${rec.seuls - sa}) · silences : ${rec.silences}`);
+    o.log(`non appariés : ${rec.ratio === null ? 'n/a' : pct(rec.ratio)} (seuil ${pct(seuil)})`);
+    for (const i of rec.items) {
+        if (i.statut === 'divergent')
+            o.log(`divergent : ${i.element.type} p.${i.element.source.page} : ${i.detail}`);
+        if (i.statut === 'seul')
+            o.log(`seul (${lectureLabel(i.lecture)}) : ${i.element.type} p.${i.element.source.page} : ${identite(i.element, new Map())}`);
+    }
+    if (rec.refuse) {
+        o.log(`plus de ${pct(seuil)} d'éléments non appariés (${rec.nonApparies} sur ${rec.concordants + rec.divergents + rec.seuls}) : les deux lectures ne décrivent pas le même document — question au lead, aucune réconciliation`);
+        return 1;
+    }
+    if (o.out !== undefined)
+        writeFileSync(o.out, `${JSON.stringify(assembler(a, b, rec), null, 2)}\n`);
+    return 0;
+}

package/dist/ref/evaluate.js

@@ -10,7 +10,7 @@ const norm = (v) => {
 const normTexte = (v) => String(v ?? '').normalize('NFC').replace(/\s+/g, ' ').trim();
 const noms = (xs, cle) => (Array.isArray(xs) ? xs.map((x) => norm(x?.[cle])) : []);
 /** Ce qui désigne un élément, indépendamment de son id, de sa zone et de sa confiance : deux lectures indépendantes numérotent à leur façon. */
-function identite(e, parId) {
+export function identite(e, parId) {
     const cible = (id) => {
         const t = typeof id === 'string' ? parId.get(id) : undefined;
         return t ? `${t.type}:${identite(t, new Map())}` : '?';
@@ -41,7 +41,7 @@ function identite(e, parId) {
     }
 }
 /** Ce que l'élément affirme une fois retrouvé : une identité juste avec une affirmation fausse est un faux lu, pas un rappel. */
-function affirmation(e, parId) {
+export function affirmation(e, parId) {
     switch (e.type) {
         case 'ecran':
             return String(e.largeur_reference);