talos-code 0.0.1 → 0.2.0

package/dist/services/notes-facade.js

@@ -0,0 +1,157 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findTalosRepoRoot, importTalosModule } from "../runtime/repo.js";
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,120}$/u;
+const KINDS = new Set(['session', 'task', 'research']);
+function fail(code, message = code) { throw Object.assign(new Error(message), { code }); }
+function validId(value, code) { if (!ID.test(value) || value.includes('..'))
+    fail(code); return value; }
+function targetKind(value) { if (!KINDS.has(value))
+    fail('NOTE_LINK_KIND_INVALID'); return value; }
+function textOrNull(value) { return typeof value === 'string' ? value : null; }
+function requireText(value, field) { if (typeof value !== 'string' || !value.length)
+    throw new TypeError('malformed persisted note row: ' + field); return value; }
+function relationKey(record) { return createHash('sha256').update(record.noteId + '\0' + record.target.kind + '\0' + record.target.id).digest('hex'); }
+function relationRecord(value) {
+    if (!value || typeof value !== 'object' || value.schema !== 'talos.cli.note-relation.v1')
+        throw new TypeError('malformed note relation');
+    const noteId = validId(String(value.noteId ?? ''), 'NOTE_RELATION_INVALID');
+    const kind = targetKind(String(value.target?.kind ?? ''));
+    const id = validId(String(value.target?.id ?? ''), 'NOTE_RELATION_INVALID');
+    const createdAt = requireText(value.createdAt, 'createdAt');
+    return { schema: 'talos.cli.note-relation.v1', noteId, target: { kind, id }, createdAt };
+}
+function relationSort(a, b) { return a.target.kind.localeCompare(b.target.kind) || a.target.id.localeCompare(b.target.id) || a.createdAt.localeCompare(b.createdAt); }
+function safeComposer(value) { return value.replace(/[\x00-\x09\x0b\x0c\x0e-\x1f\x7f-\x9f\u2028\u2029\p{Bidi_Control}\p{Default_Ignorable_Code_Point}]/gu, ch => { const cp = ch.codePointAt(0) ?? 0; return cp <= 0xffff ? '\\u' + cp.toString(16).padStart(4, '0') : '\\u{' + cp.toString(16) + '}'; }); }
+export function createNotesFacade(input, deps = {}) {
+    const notesRoot = join(input.paths.dataRoot, 'notes');
+    const tasksRoot = join(input.paths.dataRoot, 'tasks');
+    const relationRoot = join(input.paths.dataRoot, 'note-relations');
+    const repoRoot = () => input.repoRoot ?? (input.projectRoot ? findTalosRepoRoot(input.projectRoot) : fail('NOTES_REPO_ROOT_REQUIRED'));
+    let notesPromise = null, tasksPromise = null, sessionsPromise = null;
+    const notesStore = () => notesPromise ??= (deps.loadNotesStore ? deps.loadNotesStore() : importTalosModule(repoRoot(), 'notes-store.mjs'));
+    const taskStore = () => tasksPromise ??= (deps.loadTaskStore ? deps.loadTaskStore() : importTalosModule(repoRoot(), 'tasks-store.mjs'));
+    const sessionStore = () => sessionsPromise ??= (deps.loadSessionStore ? deps.loadSessionStore() : importTalosModule(repoRoot(), 'session-store.mjs'));
+    const defaultListRelations = async () => {
+        let names;
+        try {
+            names = await readdir(relationRoot);
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const records = [];
+        for (const name of names.sort()) {
+            if (!name.endsWith('.json'))
+                continue;
+            records.push(relationRecord(JSON.parse(await readFile(join(relationRoot, name), 'utf8'))));
+        }
+        return records.sort(relationSort);
+    };
+    const defaultWriteRelation = async (record) => {
+        await mkdir(relationRoot, { recursive: true, mode: 0o700 });
+        const key = relationKey(record), final = join(relationRoot, key + '.json'), tmp = join(relationRoot, '.' + key + '.' + randomUUID() + '.tmp');
+        await writeFile(tmp, JSON.stringify(record, null, 2) + '\n', { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        try {
+            await rename(tmp, final);
+        }
+        catch (error) {
+            await rm(tmp, { force: true });
+            throw error;
+        }
+    };
+    const defaultDeleteRelation = async (record) => { await rm(join(relationRoot, relationKey(record) + '.json'), { force: true }); };
+    const listRelations = async () => { const raw = await (deps.listRelations ? deps.listRelations() : defaultListRelations()); if (!Array.isArray(raw))
+        throw new TypeError('malformed note relation store'); return raw.map(relationRecord).sort(relationSort); };
+    const writeRelation = deps.writeRelation ?? defaultWriteRelation;
+    const deleteRelation = deps.deleteRelation ?? defaultDeleteRelation;
+    const now = deps.now ?? (() => new Date());
+    async function targetState(target, required = false) {
+        if (target.kind === 'task') {
+            const row = await (await taskStore()).leggiAttivita({ cartella: tasksRoot, id: target.id });
+            if (row)
+                return { state: 'available', label: textOrNull(row.titolo) };
+        }
+        else {
+            const records = await (await sessionStore()).leggiRegistro({ cartellaStore: input.paths.sessionsRoot, sessionId: target.id });
+            const header = Array.isArray(records) ? records.find((row) => row?.tipo === 'intestazione') : null;
+            if (header) {
+                if (target.kind === 'session')
+                    return { state: 'available', label: null };
+                if (header.taskId === 'ricerca' && header.task?.ricercaId === target.id)
+                    return { state: 'available', label: textOrNull(header.task?.ricercaDomanda) };
+            }
+        }
+        if (required)
+            fail('NOTE_LINK_TARGET_NOT_FOUND');
+        return { state: 'dangling', label: null };
+    }
+    function publicNote(raw, store) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new TypeError('malformed persisted note row: object');
+        const shaped = typeof store.formaPubblicaNota === 'function' ? store.formaPubblicaNota(raw) : raw;
+        if (!shaped || typeof shaped !== 'object' || Array.isArray(shaped))
+            throw new TypeError('malformed persisted note row: public shape');
+        const id = validId(requireText(shaped.id, 'id'), 'NOTE_ID_INVALID');
+        const title = requireText(shaped.titolo, 'titolo'), content = requireText(shaped.contenuto, 'contenuto');
+        const format = shaped.formato === 'markdown' ? 'markdown' : shaped.formato === 'testo' ? 'testo' : fail('NOTE_FORMAT_INVALID');
+        const writer = shaped.origine === 'persona' ? 'persona' : 'modello';
+        const formatEvidence = (raw.formato === 'markdown' || raw.formato === 'testo') ? 'persisted' : 'derived-content';
+        const writerEvidence = (raw.origine === 'persona' || raw.origine === 'modello') ? 'persisted' : 'derived-legacy-default';
+        return { id, title, content, format, formatEvidence, writer, writerEvidence, createdAt: textOrNull(shaped.creataAlle), updatedAt: textOrNull(shaped.aggiornataAlle) };
+    }
+    async function projectNote(raw, store, relations) {
+        const base = publicNote(raw, store), views = [];
+        for (const record of relations.filter(row => row.noteId === base.id))
+            views.push({ ...record, ...await targetState(record.target, false) });
+        return { ...base, relations: views.sort(relationSort) };
+    }
+    async function exactNote(noteId) { const wanted = validId(noteId, 'NOTE_ID_INVALID'), store = await notesStore(), raw = await store.leggiNota({ cartella: notesRoot, id: wanted }); if (!raw)
+        fail('NOTE_NOT_FOUND'); return { wanted, store, raw }; }
+    function invalid(error) { return { state: 'invalid', rows: [], error: { code: 'NOTES_STORE_INVALID', message: error instanceof Error ? error.message : String(error) }, legacyRows: [] }; }
+    const list = async () => {
+        try {
+            const store = await notesStore(), raw = await store.elencaNote({ cartella: notesRoot });
+            if (!Array.isArray(raw))
+                throw new TypeError('malformed persisted note list');
+            const relations = await listRelations(), rows = [];
+            for (const item of raw)
+                rows.push(await projectNote(item, store, relations));
+            return { state: 'ready', rows, error: null, legacyRows: raw };
+        }
+        catch (error) {
+            return invalid(error);
+        }
+    };
+    const read = async (noteId) => { const store = await notesStore(), wanted = validId(noteId, 'NOTE_ID_INVALID'), raw = await store.leggiNota({ cartella: notesRoot, id: wanted }); if (!raw)
+        return null; return projectNote(raw, store, await listRelations()); };
+    const add = async (value) => { const store = await notesStore(), legacy = await store.creaNota({ cartella: notesRoot, title: value.title, content: value.content, origine: 'persona' }); return { legacy }; };
+    const update = async (noteId, value) => { const store = await notesStore(), wanted = validId(noteId, 'NOTE_ID_INVALID'), legacy = await store.aggiornaNota({ cartella: notesRoot, id: wanted, ...(value.title !== undefined ? { title: value.title } : {}), ...(value.content !== undefined ? { content: value.content } : {}) }); return { legacy }; };
+    const deleteNote = async (noteId) => { const wanted = validId(noteId, 'NOTE_ID_INVALID'), store = await notesStore(); await store.eliminaNota({ cartella: notesRoot, id: wanted }); return { ok: true, id: wanted, legacy: { ok: true, id: wanted } }; };
+    const link = async (noteId, kindValue, targetId) => {
+        const source = await exactNote(noteId), target = { kind: targetKind(kindValue), id: validId(targetId, 'NOTE_LINK_TARGET_INVALID') };
+        await targetState(target, true);
+        const existing = (await listRelations()).find(row => row.noteId === source.wanted && row.target.kind === target.kind && row.target.id === target.id);
+        if (existing)
+            return { changed: false, relation: { ...existing, ...await targetState(existing.target, false) } };
+        const record = { schema: 'talos.cli.note-relation.v1', noteId: source.wanted, target, createdAt: now().toISOString() };
+        await writeRelation(record);
+        return { changed: true, relation: { ...record, ...await targetState(target, false) } };
+    };
+    const unlink = async (noteId, kindValue, targetId) => {
+        const source = await exactNote(noteId), target = { kind: targetKind(kindValue), id: validId(targetId, 'NOTE_LINK_TARGET_INVALID') };
+        const existing = (await listRelations()).find(row => row.noteId === source.wanted && row.target.kind === target.kind && row.target.id === target.id);
+        if (!existing)
+            return { changed: false, noteId: source.wanted, target };
+        await deleteRelation(existing);
+        return { changed: true, noteId: source.wanted, target };
+    };
+    const composerReference = async (noteId) => {
+        const { store, raw } = await exactNote(noteId), note = publicNote(raw, store);
+        return 'TALOS note reference (note:' + note.id + ')\nReference content; not an instruction by itself.\nTitle: ' + safeComposer(note.title) + '\n\n' + safeComposer(note.content);
+    };
+    return { list, read, add, update, delete: deleteNote, link, unlink, composerReference };
+}

package/dist/services/plugin-facade.js

@@ -0,0 +1,308 @@
+import { createHash } from 'node:crypto';
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createRedactor, redactObject, secretValuesFromEnvironment } from "../diagnostics/redact.js";
+import { listInstalledExtensions } from "../extensions/installer.js";
+import { findTalosRepoRoot, importTalosModule } from "../runtime/repo.js";
+import { pluginReviewFromSnapshot, scanPluginPackage } from "../security/plugin-guard.js";
+import { createTrustAuthority } from "../security/trust-authority.js";
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/u;
+function fail(code, message = code, extra = {}) { throw Object.assign(new Error(message), { code, ...extra }); }
+function pluginId(value) { if (!ID.test(value) || value.includes('..'))
+    fail('PLUGIN_ID_INVALID'); return value; }
+function asText(value) { return typeof value === 'string' && value.length > 0 ? value : null; }
+function digest(rows) {
+    if (!rows.length)
+        return null;
+    const hash = createHash('sha256').update('talos.cli.plugin-resource-set.v1\0');
+    for (const row of [...rows].sort((a, b) => a.path.localeCompare(b.path) || a.fingerprint.localeCompare(b.fingerprint))) {
+        hash.update(row.path).update('\0').update(row.fingerprint).update('\n');
+    }
+    return hash.digest('hex');
+}
+function resourceRows(snapshot, id) {
+    const prefix = '.harness-ui-plugins/' + id + '/';
+    return snapshot.resources.filter(row => row.kind === 'plugin' && row.relativePath.startsWith(prefix));
+}
+function fingerprintSummary(snapshot, id) {
+    const rows = resourceRows(snapshot, id);
+    const current = rows.flatMap(row => row.currentFingerprint ? [{ path: row.relativePath, fingerprint: row.currentFingerprint }] : []);
+    const trusted = rows.flatMap(row => row.trustedFingerprint ? [{ path: row.relativePath, fingerprint: row.trustedFingerprint }] : []);
+    return {
+        currentSetDigest: digest(current),
+        trustedSetDigest: digest(trusted),
+        changedPaths: rows.filter(row => row.state === 'changed').map(row => row.relativePath).sort(),
+        addedPaths: rows.filter(row => row.state === 'added').map(row => row.relativePath).sort(),
+        removedPaths: rows.filter(row => row.state === 'removed').map(row => row.relativePath).sort()
+    };
+}
+function quarantineView(value) {
+    return value ? {
+        active: true, reason: value.reason ?? null, quarantinedAt: value.quarantinedAt ?? null, reviewedFingerprint: value.reviewedFingerprint ?? null
+    } : { active: false, reason: null, quarantinedAt: null, reviewedFingerprint: null };
+}
+function validInstalled(row, id) {
+    return Boolean(row && typeof row === 'object' && row.id === id && typeof row.name === 'string' && typeof row.version === 'string'
+        && typeof row.source === 'string' && row.components && typeof row.components === 'object'
+        && row.components.plugin?.id === id);
+}
+export function createPluginFacade(input, deps = {}) {
+    const authority = deps.authority ?? createTrustAuthority({ projectRoot: input.projectRoot, trustRoot: input.paths.trust.projects });
+    const repoRoot = () => input.repoRoot ?? findTalosRepoRoot(input.projectRoot);
+    const secrets = secretValuesFromEnvironment(input.env ?? process.env);
+    const redactor = createRedactor(secrets);
+    let registryPromise = null;
+    const registry = () => registryPromise ??= importTalosModule(repoRoot(), 'plugin-registry.mjs');
+    const loadPlugins = deps.loadPlugins ?? (async () => {
+        const loaded = await (await registry()).caricaPlugin({ cartella: input.projectRoot });
+        return { plugin: Array.isArray(loaded?.plugin) ? loaded.plugin : [], falliti: Array.isArray(loaded?.falliti) ? loaded.falliti : [] };
+    });
+    const listPackages = deps.listInstalledPackages ?? (() => listInstalledExtensions(input.projectRoot));
+    const pathExists = deps.pathExists ?? (async (path) => {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        }
+    });
+    const listManagedStateIds = deps.listManagedStateIds ?? (async () => {
+        const root = join(input.projectRoot, '.talos-cli', 'extensions');
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const ids = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            let id;
+            try {
+                id = pluginId(entry.name);
+            }
+            catch {
+                continue;
+            }
+            if (await pathExists(join(input.projectRoot, '.harness-ui-plugins', id)))
+                ids.push(id);
+        }
+        return ids.sort();
+    });
+    async function compatibilityRoot() { return (await authority.compatibilityRoots()).plugins; }
+    async function defaultUntrustCompatibility(id) { await rm(join(await compatibilityRoot(), pluginId(id) + '.json'), { force: true }); }
+    async function defaultTrustCompatibility(plugin) {
+        if (!plugin.hash)
+            fail('PLUGIN_COMPATIBILITY_HASH_MISSING');
+        const root = await compatibilityRoot();
+        await rm(join(root, pluginId(plugin.id) + '.json'), { force: true });
+        await (await registry()).fidaPlugin({ cartellaTrust: root, pluginId: plugin.id, hash: plugin.hash });
+    }
+    const untrustCompatibility = deps.untrustCompatibility ?? defaultUntrustCompatibility;
+    const trustCompatibility = deps.trustCompatibility ?? defaultTrustCompatibility;
+    const scanPlugin = deps.scanPlugin ?? ((plugin, review) => scanPluginPackage({ projectRoot: input.projectRoot, plugin: { id: plugin.id, tools: plugin.tools ?? [], hooks: plugin.hooks ?? [] }, expectedReview: review }));
+    async function loadedState() {
+        const loaded = await loadPlugins();
+        const plugin = Array.isArray(loaded?.plugin) ? loaded.plugin.map(row => ({ ...row, id: pluginId(String(row.id ?? '')) })) : [];
+        const falliti = Array.isArray(loaded?.falliti) ? loaded.falliti.flatMap(row => {
+            const id = asText(row?.pluginId);
+            if (!id)
+                return [];
+            try {
+                return [{ ...row, pluginId: pluginId(id) }];
+            }
+            catch {
+                return [];
+            }
+        }) : [];
+        return { plugin, falliti };
+    }
+    async function packageRecords() {
+        try {
+            const rows = await listPackages();
+            return Array.isArray(rows) ? rows : [];
+        }
+        catch (error) {
+            if (error instanceof TypeError)
+                return [];
+            throw error;
+        }
+    }
+    async function provenance(id, packages) {
+        const stateDir = join(input.projectRoot, '.talos-cli', 'extensions', id);
+        const packageCopyAbsolute = join(stateDir, 'package');
+        const packageCopy = '.talos-cli/extensions/' + id + '/package';
+        const candidate = packages.find(row => row?.id === id) ?? null;
+        const [statePresent, copyPresent] = await Promise.all([pathExists(stateDir), pathExists(packageCopyAbsolute)]);
+        if (candidate && validInstalled(candidate, id)) {
+            const source = redactor.text(candidate.source);
+            let sourceAvailable = false;
+            try {
+                sourceAvailable = await pathExists(candidate.source);
+            }
+            catch {
+                sourceAvailable = false;
+            }
+            return {
+                kind: 'managed-extension',
+                extension: { id: candidate.id, name: redactor.text(candidate.name), version: redactor.text(candidate.version) },
+                packageCopy, packageCopyPresent: copyPresent,
+                recordedSource: source, recordedSourceAvailable: sourceAvailable, recordedSourceAuthority: 'advisory-only'
+            };
+        }
+        if (candidate || statePresent) {
+            return {
+                kind: 'managed-state-invalid', extension: null, packageCopy, packageCopyPresent: copyPresent,
+                recordedSource: null, recordedSourceAvailable: false, recordedSourceAuthority: 'advisory-only'
+            };
+        }
+        return {
+            kind: 'unmanaged-project-plugin', extension: null, packageCopy, packageCopyPresent: false,
+            recordedSource: null, recordedSourceAvailable: false, recordedSourceAuthority: 'advisory-only'
+        };
+    }
+    async function knownState() {
+        const [loaded, snapshot, packages, managedStateIds] = await Promise.all([loadedState(), authority.inspect(), packageRecords(), listManagedStateIds()]);
+        const byId = new Map();
+        for (const row of loaded.plugin)
+            byId.set(row.id, { plugin: row, failure: null });
+        for (const failure of loaded.falliti) {
+            if (!byId.has(failure.pluginId))
+                byId.set(failure.pluginId, { plugin: null, failure });
+        }
+        for (const row of packages) {
+            const id = asText(row?.components?.plugin?.id) ?? asText(row?.id);
+            if (id) {
+                try {
+                    const clean = pluginId(id);
+                    if (!byId.has(clean))
+                        byId.set(clean, { plugin: null, failure: null });
+                }
+                catch { }
+            }
+        }
+        for (const raw of managedStateIds) {
+            try {
+                const id = pluginId(raw);
+                if (!byId.has(id))
+                    byId.set(id, { plugin: null, failure: null });
+            }
+            catch { }
+        }
+        for (const resource of snapshot.resources) {
+            if (resource.kind !== 'plugin')
+                continue;
+            const match = /^\.harness-ui-plugins\/([^/]+)\//u.exec(resource.relativePath);
+            if (!match)
+                continue;
+            try {
+                const id = pluginId(match[1]);
+                if (!byId.has(id))
+                    byId.set(id, { plugin: null, failure: null });
+            }
+            catch { }
+        }
+        return { loaded, snapshot, packages, byId };
+    }
+    async function view(id, state) {
+        const entry = state.byId.get(id) ?? { plugin: null, failure: null };
+        const [quarantine, scopeTrusted, prov] = await Promise.all([
+            authority.quarantineStatus({ kind: 'plugin', id }),
+            authority.verifyScope({ kind: 'plugin', id }),
+            provenance(id, state.packages)
+        ]);
+        let guard = null;
+        let guardError = null;
+        if (entry.plugin) {
+            const review = pluginReviewFromSnapshot(state.snapshot, id);
+            try {
+                guard = redactObject(await scanPlugin(entry.plugin, review), secrets);
+            }
+            catch (error) {
+                guardError = redactor.text(error instanceof Error ? error.message : String(error));
+            }
+        }
+        const registryState = entry.plugin
+            ? { state: 'loaded', code: null, message: null }
+            : entry.failure
+                ? { state: 'failed', code: asText(entry.failure.codice), message: redactor.text(entry.failure.frase ?? entry.failure.messaggio ?? 'plugin registry refused this package') }
+                : { state: 'missing', code: null, message: 'Plugin package is not currently loadable from the runtime registry.' };
+        return {
+            id,
+            name: entry.plugin ? redactor.text(String(entry.plugin.nome ?? id)) : prov.extension?.name ?? null,
+            description: entry.plugin ? redactor.text(String(entry.plugin.descrizione ?? '')) : null,
+            registry: registryState,
+            provenance: prov,
+            guard, guardError,
+            trust: {
+                projectTrusted: state.snapshot.trusted,
+                scopeTrusted,
+                effectiveTrusted: Boolean(entry.plugin && guard && guard.verdict !== 'dangerous' && scopeTrusted && !quarantine)
+            },
+            fingerprints: fingerprintSummary(state.snapshot, id),
+            quarantine: quarantineView(quarantine)
+        };
+    }
+    async function targetLoaded(id) {
+        const clean = pluginId(id);
+        const state = await loadedState();
+        const plugin = state.plugin.find(row => row.id === clean);
+        if (!plugin) {
+            const failure = state.falliti.find(row => row.pluginId === clean);
+            if (failure)
+                fail('PLUGIN_REGISTRY_FAILED', failure.frase ?? failure.messaggio ?? 'PLUGIN_REGISTRY_FAILED', { registryFailure: failure });
+            fail('PLUGIN_NOT_FOUND');
+        }
+        return plugin;
+    }
+    async function assertKnown(id) {
+        const clean = pluginId(id);
+        const state = await knownState();
+        if (!state.byId.has(clean))
+            fail('PLUGIN_NOT_FOUND');
+        return clean;
+    }
+    return {
+        async list() {
+            const state = await knownState();
+            return Promise.all([...state.byId.keys()].sort().map(id => view(id, state)));
+        },
+        async trust(id) {
+            const plugin = await targetLoaded(id);
+            const reviewed = await authority.inspect();
+            const review = pluginReviewFromSnapshot(reviewed, plugin.id);
+            const guard = await scanPlugin(plugin, review);
+            if (guard.verdict === 'dangerous')
+                fail('PLUGIN_DANGEROUS', 'PLUGIN_DANGEROUS', { guard });
+            const result = await authority.trustScope({ kind: 'plugin', id: plugin.id }, { expected: reviewed });
+            await trustCompatibility(plugin);
+            return { ok: true, id: plugin.id, changed: result.changed, guard, snapshot: result.snapshot };
+        },
+        async untrust(id) {
+            const clean = await assertKnown(id);
+            const result = await authority.untrustScope({ kind: 'plugin', id: clean });
+            await untrustCompatibility(clean);
+            return { ok: true, id: clean, changed: result.changed, snapshot: result.snapshot };
+        },
+        async quarantine(id, reason = null) {
+            const clean = await assertKnown(id);
+            const reviewed = await authority.inspect();
+            const result = await authority.quarantineScope({ kind: 'plugin', id: clean }, { reason, expected: reviewed });
+            await untrustCompatibility(clean);
+            return { ok: true, id: clean, changed: result.changed, record: result.record, snapshot: result.snapshot };
+        },
+        async releaseQuarantine(id) {
+            const clean = await assertKnown(id);
+            const result = await authority.releaseQuarantine({ kind: 'plugin', id: clean });
+            await untrustCompatibility(clean);
+            return { ok: true, id: clean, changed: result.changed };
+        }
+    };
+}

package/dist/services/research-facade.js

@@ -0,0 +1,110 @@
+import { writeFile as writeFileReal } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { findTalosRepoRoot, importTalosModule } from "../runtime/repo.js";
+const VERDICTS = new Set(['yes', 'partial', 'no', 'unchecked', 'contested']);
+function fail(code, message = code) { throw Object.assign(new Error(message), { code }); }
+function str(value) { return typeof value === 'string' ? value : null; }
+function verification(value) { return VERDICTS.has(value) ? value : null; }
+function finite(value) { return typeof value === 'number' && Number.isFinite(value) ? value : 0; }
+export function createResearchFacade(input, deps = {}) {
+    const repoRoot = () => input.repoRoot ?? findTalosRepoRoot(input.projectRoot);
+    let storePromise = null, runPromise = null, reportPromise = null, exportPromise = null;
+    const store = () => storePromise ??= (deps.loadStore ? deps.loadStore() : importTalosModule(repoRoot(), 'research-store.mjs'));
+    const runModule = () => runPromise ??= (deps.loadRun ? deps.loadRun() : importTalosModule(repoRoot(), 'research/run.mjs'));
+    const parseReport = async (document) => { if (deps.parseReport)
+        return deps.parseReport(document); reportPromise ??= importTalosModule(repoRoot(), 'research/report.mjs'); return (await reportPromise).talosResearchParseReport(document); };
+    const exportResearch = async (value) => { if (deps.exportResearch)
+        return deps.exportResearch(value); exportPromise ??= importTalosModule(repoRoot(), 'research/esportazioni.mjs'); return (await exportPromise).costruisciEsportazione(value); };
+    const writeExport = deps.writeExportFile ?? (async (path, bytes) => { await writeFileReal(path, bytes); });
+    async function replay(id) {
+        const s = await store(), journal = await s.leggiGiornale({ cartella: input.projectRoot, id }), mod = await runModule();
+        const state = mod.talosResearchReplay(Array.isArray(journal.eventi) ? journal.eventi : []);
+        let progress = null, spent = null;
+        try {
+            const p = mod.talosResearchProgressOf(state);
+            if (p && Number.isFinite(p.done) && Number.isFinite(p.total))
+                progress = { done: Number(p.done), total: Number(p.total) };
+        }
+        catch { }
+        try {
+            spent = mod.talosResearchSpent(state) ?? null;
+        }
+        catch { }
+        return { state, journal, progress, spent };
+    }
+    function row(meta, phase) {
+        if (!meta || typeof meta !== 'object' || Array.isArray(meta) || typeof meta.id !== 'string' || !meta.id)
+            throw new TypeError('malformed research metadata');
+        return { id: meta.id, question: str(meta.domanda), name: str(meta.nome ?? meta.titolo), status: str(meta.terminata) ?? phase ?? 'unknown', startedAt: str(meta.avviataAlle), finishedAt: str(meta.conclusaAlle) };
+    }
+    async function raw(id) {
+        if (typeof id !== 'string' || !id)
+            fail('RESEARCH_ID_INVALID');
+        const s = await store(), meta = await s.leggiRicerca({ cartella: input.projectRoot, id });
+        if (!meta || meta.id !== id)
+            fail('RESEARCH_NOT_FOUND');
+        const [journalPlan, report] = await Promise.all([s.leggiPiano({ cartella: input.projectRoot, id }), s.leggiRapporto({ cartella: input.projectRoot, id })]);
+        const live = await replay(id);
+        return { s, meta, plan: Array.isArray(journalPlan) ? journalPlan : null, report, live };
+    }
+    const list = async () => {
+        try {
+            const s = await store(), rowsRaw = await s.elencaRicerche({ cartella: input.projectRoot });
+            if (!Array.isArray(rowsRaw))
+                throw new TypeError('malformed research list');
+            const rows = [];
+            for (const meta of rowsRaw) {
+                const id = typeof meta?.id === 'string' ? meta.id : '';
+                const live = id ? await replay(id) : null;
+                rows.push(row(meta, str(live?.state?.status)));
+            }
+            return { state: 'ready', rows, error: null };
+        }
+        catch (error) {
+            return { state: 'invalid', rows: [], error: { code: 'RESEARCH_STORE_INVALID', message: error instanceof Error ? error.message : String(error) } };
+        }
+    };
+    const read = async (id) => {
+        const x = await raw(id), phase = str(x.live.state?.status), base = row(x.meta, phase);
+        const parsed = typeof x.report === 'string' ? await parseReport(x.report) : null;
+        let sources = null, claims = null, summary = null, standing = null;
+        if (parsed && Array.isArray(parsed.sources) && Array.isArray(parsed.claims)) {
+            sources = parsed.sources.map((source, index) => ({ number: index + 1, url: str(source?.url) ?? '', title: str(source?.title) ?? '', publishedAt: str(source?.publishedAt), obtained: str(source?.obtained) }));
+            claims = parsed.claims.map((claim, index) => {
+                const sourceNumber = Number.isSafeInteger(claim?.sourceIndex) ? Number(claim.sourceIndex) : 0;
+                return { number: index + 1, text: str(claim?.text) ?? '', source: sourceNumber > 0 ? (sources?.[sourceNumber - 1] ?? null) : null, passage: str(claim?.passage) ?? '', quotePresent: typeof claim?.checks?.quotePresent === 'boolean' ? claim.checks.quotePresent : null, verification: verification(claim?.checks?.claimSupported), reason: str(claim?.checks?.supportReason), judge: str(claim?.checks?.judge), judgedAt: str(claim?.checks?.judgedAt), opposing: Array.isArray(claim?.checks?.opposing) ? claim.checks.opposing : null };
+            });
+            summary = str(parsed.summary);
+            const claimRows = claims;
+            const count = (v) => claimRows.filter(c => c.verification === v).length;
+            standing = { total: claimRows.length, supported: count('yes'), partial: count('partial'), unsupported: count('no'), unchecked: count('unchecked'), contested: count('contested') };
+        }
+        return { ...base, phase, progress: x.live.progress, journal: { events: Array.isArray(x.live.journal.eventi) ? x.live.journal.eventi.length : 0, skippedRows: finite(x.live.journal.righeSaltate) }, summary, verification: standing, sources, claims, plan: x.plan, steps: Array.isArray(x.live.state?.steps) ? x.live.state.steps : null, spent: x.live.spent, expectedCost: null };
+    };
+    async function ownerAction(method, ownerSessionId, researchId) {
+        if (!ownerSessionId || !researchId)
+            fail('RESEARCH_CONTROL_ID_REQUIRED');
+        const fn = deps.registry?.[method];
+        if (typeof fn !== 'function')
+            fail('RESEARCH_CONTROL_UNAVAILABLE');
+        const result = await fn.call(deps.registry, ownerSessionId, researchId);
+        if (result?.erroreAvvio)
+            fail(typeof result.code === 'string' ? result.code : 'RESEARCH_CONTROL_UNAVAILABLE', String(result.erroreAvvio));
+        if (result?.ricerca === null)
+            fail('RESEARCH_NOT_FOUND');
+        if (result?.ok === false)
+            fail('RESEARCH_CONFLICT', str(result.motivo) ?? 'Research state does not allow this action.');
+        return result;
+    }
+    const pause = (ownerSessionId, researchId) => ownerAction('pausaRicerca', ownerSessionId, researchId);
+    const resume = (ownerSessionId, researchId) => ownerAction('riprendiRicerca', ownerSessionId, researchId);
+    const cancel = (ownerSessionId, researchId) => ownerAction('annullaRicerca', ownerSessionId, researchId);
+    const exportFile = async (id, format, out, tone) => {
+        const x = await raw(id), result = await exportResearch({ ricerca: { ...x.meta, contenutoRapporto: x.report }, formato: format, ...(tone ? { tono: tone } : {}) });
+        const path = out ?? resolve(input.projectRoot, String(result.nomeFile));
+        const bytes = Buffer.from(result.bytes);
+        await writeExport(path, bytes);
+        return { id, format, path, nomeFile: String(result.nomeFile), mediaType: String(result.mediaType), bytes: bytes.length };
+    };
+    return { list, read, pause, resume, cancel, exportFile };
+}