sxng-cli 1.2.6 → 1.2.7

package/dist/deep/session.js

@@ -1,309 +1,610 @@
 /**
- * Session management for multi-round search accumulation
- *
- * A session directory contains:
- * - results.json: Accumulated search result pool (deduped by URL)
- * - graph.json: graphology knowledge graph (structural + semantic layers)
+ * Session state is the authority for discovery, extracted bodies, and approval.
+ * Every mutation uses an atomic same-directory write so an interrupted command
+ * cannot turn a valid session into an empty one.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { DirectedGraph } from 'graphology';
-import { deserializeGraph, serializeGraph, graphStats, buildStructuralEdges } from './graph.js';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+import { MultiDirectedGraph } from 'graphology';
+import { buildStructuralEdges, deserializeGraph, graphStats, resultId, serializeGraph } from './graph.js';
 import { resultUrlKey } from './dedupe.js';
 import { getDefaultSessionRoot, loadSessionMeta } from '../commands/session.js';
-/** Resolve session path. Supports:
- *  - "new": auto-create under default root with unique name
- *  - pure name (no separators): resolve to default session root
- *  - full path: return as-is
- */
-export function resolveSessionPath(sessionValue) {
-    if (sessionValue === 'new') {
-        const root = getDefaultSessionRoot();
-        if (!existsSync(root)) {
-            mkdirSync(root, { recursive: true });
-        }
-        const name = `ds_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-        return join(root, name);
+import { assertClaimsStoreReadable, loadClaims, loadEvidences, loadReviews, saveClaims, saveEvidences, saveReviews } from '../claims/store.js';
+export class SessionStateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
     }
-    // Pure name without path separators: resolve to default sessions dir
-    if (!sessionValue.includes('/') && !sessionValue.includes('\\')) {
-        const root = getDefaultSessionRoot();
-        return join(root, sessionValue);
-    }
-    return sessionValue;
 }
-/** Ensure session directory exists and write initial meta */
-export function initSessionDir(sessionDir, owner, description, query) {
-    if (!existsSync(sessionDir)) {
-        mkdirSync(sessionDir, { recursive: true });
-    }
-    // Write or update meta.json
-    const metaFile = join(sessionDir, 'meta.json');
-    const existing = loadSessionMeta(sessionDir);
-    const now = Date.now();
-    const meta = {
-        owner: owner || existing?.owner || '',
-        description: description || existing?.description || '',
-        createdAt: existing?.createdAt || now,
-        updatedAt: now,
-        query: query || existing?.query || '',
-    };
+const SESSION_LOCK_STALE_MS = 30_000;
+function atomicWriteJson(file, value) {
+    const temp = join(dirname(file), `.${file.split(/[\\/]/).pop()}.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync(temp, JSON.stringify(value, null, 2), 'utf-8');
     try {
-        writeFileSync(metaFile, JSON.stringify(meta, null, 2), 'utf-8');
+        renameSync(temp, file);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch { /* preserve the original write error */ }
+        throw error;
     }
-    catch { /* meta write failure is non-critical */ }
 }
-/** Load accumulated results from session, or return empty */
-export function loadSessionResults(sessionDir) {
-    const file = join(sessionDir, 'results.json');
-    if (!existsSync(file))
-        return [];
+function withSessionLock(sessionDir, action) {
+    mkdirSync(sessionDir, { recursive: true });
+    const lockDir = join(sessionDir, '.lock');
+    let acquired = false;
     try {
-        const raw = readFileSync(file, 'utf-8');
-        const parsed = JSON.parse(raw);
-        if (parsed.status === 'ok' && parsed.data?.results) {
-            return parsed.data.results;
+        try {
+            mkdirSync(lockDir);
+            acquired = true;
         }
-        return [];
+        catch (error) {
+            try {
+                const age = Date.now() - statSync(lockDir).mtimeMs;
+                if (age > SESSION_LOCK_STALE_MS)
+                    rmSync(lockDir, { recursive: true, force: true });
+                else
+                    throw error;
+                mkdirSync(lockDir);
+                acquired = true;
+            }
+            catch {
+                throw new SessionStateError('SESSION_BUSY', `Session is busy: ${sessionDir}`);
+            }
+        }
+        return action();
     }
-    catch {
-        return [];
+    finally {
+        if (acquired) {
+            try {
+                rmSync(lockDir, { recursive: true, force: true });
+            }
+            catch { /* lock cleanup is best effort */ }
+        }
     }
 }
-/** Append new results to session results (dedup by normalized URL).
- *  New results are marked as 'pending' and will not be injected into graph
- *  until approved by Agent quality assessment.
- */
-export function appendSessionResults(sessionDir, newResults, options) {
-    // Ensure session directory exists
-    if (!existsSync(sessionDir)) {
-        mkdirSync(sessionDir, { recursive: true });
+/** Keep related session artifacts consistent while one command updates them. */
+export function mutateSessionState(sessionDir, action) {
+    return withSessionLock(sessionDir, () => {
+        repairInvalidDependents(sessionDir, loadSessionResults(sessionDir));
+        return action();
+    });
+}
+function originKey(origin) {
+    return `${origin.tool}\0${origin.engine ?? ''}\0${origin.query}\0${origin.round ?? ''}`;
+}
+function mergeOrigins(target, additions, round) {
+    const normalized = additions.map(origin => ({
+        ...origin,
+        ...(round !== undefined && origin.round === undefined ? { round } : {}),
+    }));
+    const merged = new Map(target.origins.map(origin => [originKey(origin), origin]));
+    for (const origin of normalized)
+        merged.set(originKey(origin), origin);
+    const next = [...merged.values()];
+    const changed = JSON.stringify(next) !== JSON.stringify(target.origins);
+    target.origins = next;
+    return changed;
+}
+function isDirectOrigin(origin) {
+    return origin.tool === 'user' || origin.tool === 'agent';
+}
+function needsRound(result) {
+    return (result.origins ?? []).some(origin => !isDirectOrigin(origin) && origin.round === undefined);
+}
+function inferredContentType(result) {
+    if (result.contentType)
+        return result.contentType;
+    return typeof result.content === 'string' && typeof result.extractedAt === 'number' ? 'extracted' : 'search';
+}
+function makeResult(input, round) {
+    const contentType = inferredContentType(input);
+    const now = Date.now();
+    const result = {
+        ...input,
+        id: resultId(input.url),
+        revision: 1,
+        url: input.url,
+        title: input.title,
+        contentType,
+        origins: [],
+        status: 'pending',
+    };
+    if (contentType === 'search') {
+        delete result.content;
+        delete result.extractor;
+        delete result.extractedAt;
     }
-    const existing = loadSessionResults(sessionDir);
-    const currentRounds = loadSessionRounds(sessionDir) || 0;
-    const round = options?.skipRoundIncrement
-        ? Math.max(1, currentRounds)
-        : Math.max(1, currentRounds + 1);
-    const urlMap = new Map();
-    for (const r of existing) {
-        urlMap.set(resultUrlKey(r), r);
+    else {
+        result.content = input.content ?? '';
+        result.extractor = input.extractor || 'default';
+        result.extractedAt = input.extractedAt ?? now;
     }
-    const mergeOrigins = (target, origins) => {
-        if (!origins?.length)
+    mergeOrigins(result, input.origins ?? [], round);
+    return result;
+}
+function touch(result) {
+    result.revision += 1;
+}
+function pruneGraphProvenance(graph, resultIdValue) {
+    let changed = false;
+    const nodesToDrop = [];
+    graph.forEachNode((node, attrs) => {
+        if (!attrs.sourceResultIds?.includes(resultIdValue))
             return;
-        const combined = [...(target.origins || []), ...origins];
-        target.origins = Array.from(new Map(combined.map(origin => [`${origin.round ?? round}\0${origin.query}`, { ...origin, round: origin.round ?? round }])).values());
-    };
-    // Add new results (dedup: keep first occurrence)
-    let added = 0;
-    const approvedResults = [];
-    for (const r of newResults) {
-        const norm = resultUrlKey(r);
-        const existingResult = urlMap.get(norm);
-        if (existingResult) {
-            const originCount = existingResult.origins?.length ?? 0;
-            mergeOrigins(existingResult, r.origins);
-            if (existingResult.status === 'approved' && (existingResult.origins?.length ?? 0) > originCount) {
-                approvedResults.push(existingResult);
-            }
-            continue;
+        const sourceResultIds = attrs.sourceResultIds.filter(id => id !== resultIdValue);
+        if (sourceResultIds.length) {
+            graph.mergeNodeAttributes(node, { sourceResultIds });
+            changed = true;
         }
-        // Mark new results as pending
-        r.status = 'pending';
-        mergeOrigins(r, r.origins);
-        urlMap.set(norm, r);
-        added++;
+        else
+            nodesToDrop.push(node);
+    });
+    for (const node of nodesToDrop) {
+        graph.dropNode(node);
+        changed = true;
     }
-    const all = Array.from(urlMap.values());
-    const rounds = round;
-    const file = join(sessionDir, 'results.json');
-    try {
-        writeFileSync(file, JSON.stringify({
-            status: 'ok',
-            data: { results: all, rounds },
-        }, null, 2), 'utf-8');
+    const edgesToDrop = [];
+    graph.forEachEdge((edge, attrs) => {
+        if (!attrs.sourceResultIds?.includes(resultIdValue))
+            return;
+        const sourceResultIds = attrs.sourceResultIds.filter(id => id !== resultIdValue);
+        if (sourceResultIds.length) {
+            graph.replaceEdgeAttributes(edge, { ...attrs, sourceResultIds });
+            changed = true;
+        }
+        else
+            edgesToDrop.push(edge);
+    });
+    for (const edge of edgesToDrop) {
+        graph.dropEdge(edge);
+        changed = true;
     }
-    catch (e) {
-        throw new Error(`Failed to write session results to ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    if (graph.hasNode(resultIdValue)) {
+        graph.dropNode(resultIdValue);
+        changed = true;
     }
-    return { added, total: all.length, approvedResults };
+    // Path nodes derive from semantic entities and are invalid once an input entity disappears.
+    const pathsToDrop = [];
+    graph.forEachNode((node, attrs) => {
+        if (attrs.type === 'path' && attrs.entities?.some(entity => !graph.hasNode(entity)))
+            pathsToDrop.push(node);
+    });
+    for (const node of pathsToDrop) {
+        graph.dropNode(node);
+        changed = true;
+    }
+    const structuralNodesToDrop = [];
+    graph.forEachNode((node, attrs) => {
+        if ((attrs.type === 'query' || attrs.type === 'domain') && graph.degree(node) === 0)
+            structuralNodesToDrop.push(node);
+    });
+    for (const node of structuralNodesToDrop) {
+        graph.dropNode(node);
+        changed = true;
+    }
+    return changed;
 }
-/** Load graph from session, or create empty */
-export function loadSessionGraph(sessionDir) {
-    const file = join(sessionDir, 'graph.json');
+function writeResults(sessionDir, results, rounds) {
+    atomicWriteJson(join(sessionDir, 'results.json'), { status: 'ok', data: { results, rounds } });
+}
+function readResultsFile(sessionDir) {
+    const file = join(sessionDir, 'results.json');
     if (!existsSync(file))
-        return new DirectedGraph();
+        return undefined;
     try {
-        const raw = readFileSync(file, 'utf-8');
-        const parsed = JSON.parse(raw);
-        const graphData = parsed.status === 'ok' && parsed.data?.graph
-            ? parsed.data.graph
-            : (parsed.nodes && parsed.edges ? parsed : null);
-        if (graphData) {
-            return deserializeGraph(graphData);
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        if (parsed.status !== 'ok' || !Array.isArray(parsed.data?.results) || !Number.isSafeInteger(parsed.data.rounds)) {
+            throw new Error('invalid results envelope');
         }
-        return new DirectedGraph();
+        return parsed;
     }
-    catch {
-        return new DirectedGraph();
+    catch (error) {
+        throw new SessionStateError('SESSION_CORRUPTED', `Cannot read session results: ${file}`);
     }
 }
-/** Save graph to session */
-export function saveSessionGraph(sessionDir, graph) {
-    const serialized = serializeGraph(graph);
-    const stats = graphStats(graph);
-    const file = join(sessionDir, 'graph.json');
-    try {
-        writeFileSync(file, JSON.stringify({
-            status: 'ok',
-            data: { graph: serialized, stats },
-        }, null, 2), 'utf-8');
-    }
-    catch (e) {
-        throw new Error(`Failed to write session graph to ${file}: ${e instanceof Error ? e.message : String(e)}`);
+function touchMeta(sessionDir) {
+    const existing = loadSessionMeta(sessionDir);
+    if (!existing)
+        return;
+    atomicWriteJson(join(sessionDir, 'meta.json'), { ...existing, updatedAt: Date.now() });
+}
+/** A result may enter evidence and semantic workflows only with a captured body. */
+export function hasVerifiedContent(result) {
+    return result.contentType === 'extracted'
+        && typeof result.content === 'string'
+        && result.content.trim().length > 0
+        && typeof result.extractedAt === 'number'
+        && Number.isFinite(result.extractedAt)
+        && result.extractedAt > 0
+        && typeof result.extractor === 'string'
+        && result.extractor.length > 0;
+}
+export function resolveSessionPath(sessionValue) {
+    if (sessionValue === 'new') {
+        const root = getDefaultSessionRoot();
+        mkdirSync(root, { recursive: true });
+        return join(root, `ds_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`);
     }
+    return !sessionValue.includes('/') && !sessionValue.includes('\\')
+        ? join(getDefaultSessionRoot(), sessionValue)
+        : sessionValue;
+}
+export function initSessionDir(sessionDir, owner, description, query) {
+    mkdirSync(sessionDir, { recursive: true });
+    mkdirSync(join(sessionDir, 'agent-inputs'), { recursive: true });
+    const existing = loadSessionMeta(sessionDir);
+    const now = Date.now();
+    const meta = {
+        owner: owner || existing?.owner || '',
+        description: description || existing?.description || '',
+        createdAt: existing?.createdAt || now,
+        updatedAt: now,
+        query: query || existing?.query || '',
+    };
+    atomicWriteJson(join(sessionDir, 'meta.json'), meta);
 }
-/** Get pending results (not yet approved by Agent) */
+/** Agent write inputs must belong to exactly the session being mutated. */
+export function validateSessionInputFile(sessionDir, inputFile) {
+    const inputsDir = resolve(sessionDir, 'agent-inputs');
+    const candidate = resolve(inputFile);
+    const rel = relative(inputsDir, candidate);
+    if (rel === '' || rel.startsWith('..') || rel.includes(':') || !existsSync(candidate))
+        return undefined;
+    return candidate;
+}
+export function loadSessionResults(sessionDir) {
+    const data = readResultsFile(sessionDir);
+    return data?.data.results ?? [];
+}
+export function loadSessionRounds(sessionDir) {
+    return readResultsFile(sessionDir)?.data.rounds ?? 0;
+}
+export function appendSessionResults(sessionDir, newResults, options) {
+    return withSessionLock(sessionDir, () => {
+        const state = readResultsFile(sessionDir);
+        const results = state?.data.results ?? [];
+        const currentRounds = state?.data.rounds ?? 0;
+        const incrementRound = !options?.skipRoundIncrement && newResults.some(needsRound);
+        const round = incrementRound ? currentRounds + 1 : currentRounds;
+        const byKey = new Map(results.map(result => [resultUrlKey(result), result]));
+        let added = 0;
+        let updated = 0;
+        const approvedResults = [];
+        for (const input of newResults) {
+            const key = resultUrlKey(input);
+            const existing = byKey.get(key);
+            const importRound = needsRound(input) ? Math.max(1, round) : undefined;
+            if (!existing) {
+                const created = makeResult(input, importRound);
+                byKey.set(key, created);
+                added++;
+                continue;
+            }
+            let changed = mergeOrigins(existing, input.origins ?? [], importRound);
+            if (inferredContentType(input) === 'extracted') {
+                const nextContent = input.content ?? '';
+                const bodyChanged = existing.contentType !== 'extracted' || existing.content !== nextContent;
+                const nextExtractedAt = input.extractedAt ?? Date.now();
+                if (bodyChanged) {
+                    existing.contentType = 'extracted';
+                    existing.content = nextContent;
+                    changed = true;
+                }
+                if (existing.extractor !== (input.extractor || 'default')) {
+                    existing.extractor = input.extractor || 'default';
+                    changed = true;
+                }
+                if (existing.extractedAt !== nextExtractedAt) {
+                    existing.extractedAt = nextExtractedAt;
+                    changed = true;
+                }
+                // An imported body is a fresh Agent input, even when its text is unchanged.
+                if (existing.skippedAt !== undefined) {
+                    existing.skippedAt = undefined;
+                    changed = true;
+                }
+                if (existing.failureCount !== undefined || existing.lastFailedAt !== undefined || existing.lastFailure !== undefined) {
+                    existing.failureCount = undefined;
+                    existing.lastFailedAt = undefined;
+                    existing.lastFailure = undefined;
+                    changed = true;
+                }
+                if (existing.status !== 'pending') {
+                    existing.status = 'pending';
+                    changed = true;
+                }
+            }
+            if (input.title && input.title !== existing.title) {
+                existing.title = input.title;
+                changed = true;
+            }
+            if (input.excerpt !== undefined && input.excerpt !== existing.excerpt) {
+                existing.excerpt = input.excerpt;
+                changed = true;
+            }
+            if (changed) {
+                touch(existing);
+                updated++;
+                if (existing.status === 'approved')
+                    approvedResults.push(existing);
+            }
+        }
+        const all = [...byKey.values()];
+        writeResults(sessionDir, all, round);
+        repairInvalidDependents(sessionDir, all);
+        touchMeta(sessionDir);
+        return { added, updated, total: all.length, round, approvedResults };
+    });
+}
+export function getPendingExtractionResults(sessionDir) {
+    return loadSessionResults(sessionDir).filter(result => result.contentType === 'search'
+        && !result.skippedAt
+        && (result.failureCount ?? 0) < 2);
+}
+/** Extracted records awaiting an approval decision. */
 export function getPendingResults(sessionDir) {
-    const results = loadSessionResults(sessionDir);
-    return results.filter(r => !r.status || r.status === 'pending');
+    return loadSessionResults(sessionDir).filter(result => result.status === 'pending'
+        && !result.skippedAt
+        && hasVerifiedContent(result));
 }
-/** Get approved results (ready for graph injection) */
 export function getApprovedResults(sessionDir) {
-    const results = loadSessionResults(sessionDir);
-    return results.filter(r => r.status === 'approved');
+    return loadSessionResults(sessionDir).filter(result => result.status === 'approved' && !result.skippedAt && hasVerifiedContent(result));
 }
-/** Approve results by their indices (0-based) in the pending list.
- *  Returns the number of approved results.
- */
-export function approveResults(sessionDir, indices) {
-    const results = loadSessionResults(sessionDir);
-    const pending = results.filter(r => !r.status || r.status === 'pending');
-    // Keep local chunk fragments so selecting one chunk does not approve its siblings.
-    const approvedResultKeys = new Set();
-    for (const idx of indices) {
-        if (idx >= 0 && idx < pending.length) {
-            approvedResultKeys.add(resultUrlKey(pending[idx]));
+function repairInvalidDependents(sessionDir, results) {
+    const invalidReasons = new Map(results
+        .filter(result => result.skippedAt || result.status !== 'approved' || !hasVerifiedContent(result))
+        .map(result => [result.id, result.skippedAt ? 'sourceSkipped' : 'contentChanged']));
+    if (!invalidReasons.size)
+        return;
+    try {
+        assertClaimsStoreReadable(sessionDir);
+        const evidences = loadEvidences(sessionDir);
+        const affectedClaims = new Set();
+        const now = Date.now();
+        let evidenceChanged = false;
+        for (const evidence of evidences) {
+            const reason = invalidReasons.get(evidence.resultId);
+            if (reason) {
+                affectedClaims.add(evidence.claimId);
+            }
+            if (reason && !evidence.invalid) {
+                evidence.invalid = true;
+                evidence.invalidatedAt = now;
+                evidence.invalidationReason = reason;
+                evidenceChanged = true;
+            }
         }
-    }
-    // Update status
-    let approved = 0;
-    const approvedResults = [];
-    for (const r of results) {
-        if (approvedResultKeys.has(resultUrlKey(r))) {
-            r.status = 'approved';
-            approved++;
-            approvedResults.push(r);
+        if (affectedClaims.size) {
+            if (evidenceChanged)
+                saveEvidences(sessionDir, evidences);
+            const claims = loadClaims(sessionDir);
+            for (const claim of claims)
+                if (affectedClaims.has(claim.id))
+                    claim.status = 'verifying';
+            saveClaims(sessionDir, claims);
+            saveReviews(sessionDir, loadReviews(sessionDir).filter(review => !affectedClaims.has(review.claimId)));
         }
     }
-    // Save back
-    const file = join(sessionDir, 'results.json');
-    const rounds = loadSessionRounds(sessionDir);
+    catch { /* Preserve corrupt claim artifacts for their dedicated repair commands. */ }
     try {
-        writeFileSync(file, JSON.stringify({
-            status: 'ok',
-            data: { results, rounds },
-        }, null, 2), 'utf-8');
+        const { graph, missing } = readSessionGraph(sessionDir);
+        if (!missing) {
+            let graphChanged = false;
+            for (const resultIdValue of invalidReasons.keys())
+                graphChanged = pruneGraphProvenance(graph, resultIdValue) || graphChanged;
+            if (graphChanged)
+                writeSessionGraph(sessionDir, graph);
+        }
     }
-    catch (e) {
-        throw new Error(`Failed to write session results to ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    catch (error) {
+        if (!(error instanceof SessionStateError))
+            throw error;
     }
-    return { approved, total: results.length, approvedResults };
 }
-/** Inject approved results into graph (structural layer).
- *  Uses query from session meta.json if not provided.
- */
-export function injectApprovedResults(sessionDir, approved) {
-    if (approved.length === 0) {
-        return { nodesAdded: 0, edgesAdded: 0 };
+export function approveResults(sessionDir, selections) {
+    return withSessionLock(sessionDir, () => {
+        const state = readResultsFile(sessionDir);
+        const results = state?.data.results ?? [];
+        repairInvalidDependents(sessionDir, results);
+        const selected = new Set();
+        for (const selection of selections) {
+            const result = results.find(item => item.id === selection.id);
+            if (!result)
+                return { approved: 0, total: results.length, approvedResults: [], error: { code: 'RESULT_NOT_FOUND', message: `Result not found: ${selection.id}`, id: selection.id } };
+            if (result.revision !== selection.revision)
+                return { approved: 0, total: results.length, approvedResults: [], error: { code: 'RESULT_REVISION_CONFLICT', message: `Result revision changed: ${selection.id}`, id: selection.id, revision: result.revision } };
+            if (result.skippedAt)
+                return { approved: 0, total: results.length, approvedResults: [], error: { code: 'RESULT_SKIPPED', message: `Result is skipped: ${selection.id}`, id: selection.id } };
+            if (!hasVerifiedContent(result))
+                return { approved: 0, total: results.length, approvedResults: [], error: { code: 'RESULT_NOT_VERIFIED', message: `Result has no extracted body: ${selection.id}`, id: selection.id } };
+            selected.add(result.id);
+        }
+        const approvedResults = [];
+        for (const result of results) {
+            if (selected.has(result.id) && result.status !== 'approved') {
+                result.status = 'approved';
+                touch(result);
+                approvedResults.push(result);
+            }
+        }
+        writeResults(sessionDir, results, state?.data.rounds ?? 0);
+        touchMeta(sessionDir);
+        return { approved: approvedResults.length, total: results.length, approvedResults };
+    });
+}
+export function setSkipped(sessionDir, selections, skipped) {
+    return withSessionLock(sessionDir, () => {
+        const state = readResultsFile(sessionDir);
+        const results = state?.data.results ?? [];
+        const selected = [];
+        const selectedIds = new Set();
+        for (const selection of selections) {
+            const result = results.find(item => item.id === selection.id);
+            if (!result)
+                return { changed: 0, results: [], error: { code: 'RESULT_NOT_FOUND', message: `Result not found: ${selection.id}`, id: selection.id } };
+            if (result.revision !== selection.revision)
+                return { changed: 0, results: [], error: { code: 'RESULT_REVISION_CONFLICT', message: `Result revision changed: ${selection.id}`, id: selection.id, revision: result.revision } };
+            if (!selectedIds.has(result.id)) {
+                selectedIds.add(result.id);
+                selected.push(result);
+            }
+        }
+        let changed = 0;
+        for (const result of selected) {
+            const shouldChange = skipped ? result.skippedAt === undefined : result.skippedAt !== undefined;
+            if (shouldChange) {
+                const wasSkipped = result.skippedAt !== undefined;
+                result.skippedAt = skipped ? Date.now() : undefined;
+                if (wasSkipped && !skipped && result.status === 'approved')
+                    result.status = 'pending';
+                touch(result);
+                changed++;
+            }
+        }
+        writeResults(sessionDir, results, state?.data.rounds ?? 0);
+        repairInvalidDependents(sessionDir, results);
+        touchMeta(sessionDir);
+        return { changed, results: selected };
+    });
+}
+export function recordExtractionOutcome(sessionDir, outcomes) {
+    return withSessionLock(sessionDir, () => {
+        const state = readResultsFile(sessionDir);
+        const results = state?.data.results ?? [];
+        const byKey = new Map(results.map(result => [resultUrlKey(result), result]));
+        let updated = 0;
+        let failed = 0;
+        for (const outcome of outcomes) {
+            const result = byKey.get(resultUrlKey({ url: outcome.url }));
+            if (!result)
+                continue;
+            if (outcome.failure) {
+                result.failureCount = (result.failureCount ?? 0) + 1;
+                result.lastFailedAt = Date.now();
+                result.lastFailure = outcome.failure;
+                touch(result);
+                failed++;
+                continue;
+            }
+            if (typeof outcome.content !== 'string' || !outcome.content.trim())
+                continue;
+            const wasSkipped = result.skippedAt !== undefined;
+            const changedBody = result.contentType !== 'extracted' || result.content !== outcome.content;
+            result.contentType = 'extracted';
+            result.content = outcome.content;
+            result.extractor = outcome.extractor || 'default';
+            result.extractedAt = outcome.extractedAt ?? Date.now();
+            result.title = outcome.title || result.title;
+            if (outcome.excerpt !== undefined)
+                result.excerpt = outcome.excerpt;
+            if (outcome.byline !== undefined)
+                result.byline = outcome.byline;
+            if (outcome.siteName !== undefined)
+                result.siteName = outcome.siteName;
+            if (outcome.length !== undefined)
+                result.contentLength = outcome.length;
+            result.skippedAt = undefined;
+            result.failureCount = undefined;
+            result.lastFailedAt = undefined;
+            result.lastFailure = undefined;
+            if ((changedBody || wasSkipped) && result.status === 'approved')
+                result.status = 'pending';
+            touch(result);
+            updated++;
+        }
+        writeResults(sessionDir, results, state?.data.rounds ?? 0);
+        repairInvalidDependents(sessionDir, results);
+        touchMeta(sessionDir);
+        return { updated, failed, total: results.length };
+    });
+}
+/** Compatibility name for callers that already provide extraction output. */
+export function mergeExtractedContent(sessionDir, extracted) {
+    const result = recordExtractionOutcome(sessionDir, extracted.map(item => item.error
+        ? { url: item.url, failure: { code: 'tool', message: item.error } }
+        : item));
+    return { updated: result.updated, total: result.total };
+}
+function readSessionGraph(sessionDir) {
+    const file = join(sessionDir, 'graph.json');
+    if (!existsSync(file))
+        return { graph: new MultiDirectedGraph(), missing: true };
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
+        const graphData = parsed.status === 'ok' && parsed.data?.graph ? parsed.data.graph : null;
+        if (!graphData)
+            throw new Error('invalid graph envelope');
+        return { graph: deserializeGraph(graphData), missing: false };
     }
-    const graph = loadSessionGraph(sessionDir);
-    const beforeNodes = graph.order;
-    const beforeEdges = graph.size;
+    catch {
+        throw new SessionStateError('SESSION_CORRUPTED', `Cannot read session graph: ${file}`);
+    }
+}
+export function loadSessionGraph(sessionDir) {
+    return withSessionLock(sessionDir, () => {
+        repairInvalidDependents(sessionDir, loadSessionResults(sessionDir));
+        return readSessionGraph(sessionDir).graph;
+    });
+}
+function writeSessionGraph(sessionDir, graph) {
+    atomicWriteJson(join(sessionDir, 'graph.json'), { status: 'ok', data: { graph: serializeGraph(graph), stats: graphStats(graph) } });
+    touchMeta(sessionDir);
+}
+function buildApprovedStructuralEdges(graph, approved) {
     const groups = new Map();
     for (const result of approved) {
-        for (const origin of result.origins || []) {
-            const key = `${origin.round ?? 0}\0${origin.query}`;
+        for (const origin of result.origins) {
+            const key = `${origin.round ?? ''}\0${origin.query}`;
             const group = groups.get(key) ?? { query: origin.query, round: origin.round, results: [] };
-            group.results.push({ url: result.url, title: result.title, source: result.source });
+            group.results.push({ url: result.url, title: result.title, origins: result.origins });
             groups.set(key, group);
         }
     }
-    for (const group of groups.values()) {
+    for (const group of groups.values())
         buildStructuralEdges(graph, group.query, group.results, group.round);
-    }
-    saveSessionGraph(sessionDir, graph);
-    return { nodesAdded: graph.order - beforeNodes, edgesAdded: graph.size - beforeEdges };
 }
-/** Count pending results */
+/** Serialize graph read-modify-write operations under one session lock. */
+export function mutateSessionGraph(sessionDir, action, options) {
+    return withSessionLock(sessionDir, () => {
+        repairInvalidDependents(sessionDir, loadSessionResults(sessionDir));
+        const { graph, missing } = readSessionGraph(sessionDir);
+        // Results are authoritative; a missing derived graph can safely regain its structural layer.
+        const approved = getApprovedResults(sessionDir);
+        if (missing && options?.reconcileStructural)
+            buildApprovedStructuralEdges(graph, approved);
+        const value = action(graph, approved);
+        writeSessionGraph(sessionDir, graph);
+        return value;
+    });
+}
+export function injectApprovedResults(sessionDir, approved) {
+    const verified = approved.filter(hasVerifiedContent);
+    if (!verified.length)
+        return { nodesAdded: 0, edgesAdded: 0 };
+    return mutateSessionGraph(sessionDir, graph => {
+        const beforeNodes = graph.order;
+        const beforeEdges = graph.size;
+        // Rebuild all approved structure when graph.json is absent, then add this approval.
+        buildApprovedStructuralEdges(graph, getApprovedResults(sessionDir));
+        return { nodesAdded: graph.order - beforeNodes, edgesAdded: graph.size - beforeEdges };
+    });
+}
 export function countPendingResults(sessionDir) {
     return getPendingResults(sessionDir).length;
 }
 export function updateSessionGraph(sessionDir, query, results, round) {
-    const graph = loadSessionGraph(sessionDir);
-    const beforeNodes = graph.order;
-    const beforeEdges = graph.size;
-    buildStructuralEdges(graph, query, results, round);
-    saveSessionGraph(sessionDir, graph);
-    return {
-        nodesAdded: graph.order - beforeNodes,
-        edgesAdded: graph.size - beforeEdges,
-    };
-}
-/** Merge extracted content into session results (update content field by URL match) */
-export function mergeExtractedContent(sessionDir, extracted) {
-    const results = loadSessionResults(sessionDir);
-    const urlMap = new Map();
-    for (const r of results) {
-        urlMap.set(resultUrlKey(r), r);
-    }
-    let updated = 0;
-    for (const ex of extracted) {
-        if (ex.error)
-            continue;
-        const norm = resultUrlKey({ url: ex.url, source: ex.url.startsWith('file:') ? 'local' : undefined });
-        const existing = urlMap.get(norm);
-        if (existing) {
-            existing.content = ex.content;
-            if (ex.excerpt)
-                existing.excerpt = ex.excerpt;
-            if (ex.byline)
-                existing.byline = ex.byline;
-            if (ex.siteName)
-                existing.siteName = ex.siteName;
-            if (ex.length)
-                existing.contentLength = ex.length;
-            if (ex.extractedAt !== undefined)
-                existing.extractedAt = ex.extractedAt;
-            updated++;
-        }
-    }
-    const all = Array.from(urlMap.values());
-    const file = join(sessionDir, 'results.json');
-    const rounds = loadSessionRounds(sessionDir) || results.length;
-    try {
-        writeFileSync(file, JSON.stringify({
-            status: 'ok',
-            data: { results: all, rounds },
-        }, null, 2), 'utf-8');
-    }
-    catch (e) {
-        throw new Error(`Failed to write session results to ${file}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    return { updated, total: all.length };
-}
-/** Get current round number from results file */
-export function loadSessionRounds(sessionDir) {
-    const file = join(sessionDir, 'results.json');
-    if (!existsSync(file))
-        return 0;
-    try {
-        const raw = readFileSync(file, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return parsed.data?.rounds || 0;
-    }
-    catch {
-        return 0;
-    }
+    const verified = results.filter(hasVerifiedContent);
+    if (!verified.length)
+        return { nodesAdded: 0, edgesAdded: 0 };
+    return mutateSessionGraph(sessionDir, graph => {
+        const beforeNodes = graph.order;
+        const beforeEdges = graph.size;
+        buildStructuralEdges(graph, query, verified.map(result => ({ url: result.url, title: result.title, origins: result.origins })), round);
+        return { nodesAdded: graph.order - beforeNodes, edgesAdded: graph.size - beforeEdges };
+    });
 }
 //# sourceMappingURL=session.js.map