papergod 0.1.0

package/src/server/review-panel.js

@@ -0,0 +1,263 @@
+import { createHash, randomUUID } from 'crypto';
+import { readFile } from 'fs/promises';
+import { sanitizePath } from './security.js';
+import { loadProject, updateProject } from './project-store.js';
+import { createAgentRun, updateAgentRun } from './project-resources.js';
+import { syncDocumentStructure } from './document-structure.js';
+import { runAcademicReviewAgent } from './agent-adapters.js';
+import { agentFailureAudit } from './agent-errors.js';
+import { createRevisionPlan } from './revision-engine.js';
+import { materializeLibraries } from './library-files.js';
+
+const REVIEW_ROLES = ['methodology', 'statistics', 'writing', 'domain', 'reproducibility'];
+const VERDICTS = ['accept', 'minor-revision', 'major-revision', 'reject'];
+const SEVERITY_RANK = { info: 0, minor: 1, major: 2, critical: 3 };
+
+export const REVIEWER_PROFILES = [
+  { id: 'methodology', name: 'Methodology reviewer', role: 'methodology', focus: 'Research design, assumptions, validity, baselines, controls, and whether conclusions follow from the method.', prompt: '' },
+  { id: 'statistics', name: 'Statistical reviewer', role: 'statistics', focus: 'Statistical design, uncertainty, effect sizes, power, multiple comparisons, and validity of quantitative claims.', prompt: '' },
+  { id: 'writing', name: 'Academic writing reviewer', role: 'writing', focus: 'Clarity, structure, terminology, claim precision, academic style, and reader comprehension.', prompt: '' },
+  { id: 'domain', name: 'Domain reviewer', role: 'domain', focus: 'Novelty, domain assumptions, related work, significance, and correctness from the target field perspective.', prompt: '' },
+  { id: 'reproducibility', name: 'Reproducibility reviewer', role: 'reproducibility', focus: 'Data, code, parameters, environment, protocols, ablations, and information needed to reproduce results.', prompt: '' },
+];
+
+export const DEFAULT_REVIEW_RUBRIC = [
+  { id: 'rigor', title: 'Technical rigor', instruction: 'Check correctness, assumptions, design, and threats to validity.', weight: 1 },
+  { id: 'evidence', title: 'Evidence and claims', instruction: 'Check whether every important claim is supported and calibrated.', weight: 1 },
+  { id: 'clarity', title: 'Clarity and organization', instruction: 'Check structure, definitions, precision, and readability.', weight: 0.8 },
+  { id: 'reproducibility', title: 'Reproducibility', instruction: 'Check whether a competent reader could reproduce the work.', weight: 1 },
+];
+
+function now() { return new Date().toISOString(); }
+function id(prefix) { return `${prefix}_${randomUUID()}`; }
+function hash(value) { return createHash('sha256').update(value).digest('hex'); }
+function problem(message, status = 400) { const error = new Error(message); error.status = status; return error; }
+function clean(value) { return typeof value === 'string' ? value.trim() : ''; }
+
+function validateReviewer(input, index) {
+  const reviewer = {
+    id: clean(input?.id) || id('reviewer'), name: clean(input?.name), role: clean(input?.role),
+    focus: clean(input?.focus), prompt: clean(input?.prompt),
+  };
+  if (!reviewer.name || !reviewer.focus) throw problem(`reviewers[${index}] needs name and focus`);
+  if (!REVIEW_ROLES.includes(reviewer.role)) throw problem(`reviewers[${index}].role must be one of: ${REVIEW_ROLES.join(', ')}`);
+  return reviewer;
+}
+
+function validateRubric(input, index) {
+  const rubric = {
+    id: clean(input?.id) || id('rubric'), title: clean(input?.title), instruction: clean(input?.instruction),
+    weight: typeof input?.weight === 'number' ? input.weight : 1,
+  };
+  if (!rubric.title || !rubric.instruction) throw problem(`rubric[${index}] needs title and instruction`);
+  if (!Number.isFinite(rubric.weight) || rubric.weight <= 0 || rubric.weight > 10) throw problem(`rubric[${index}].weight must be greater than 0 and at most 10`);
+  return rubric;
+}
+
+export function getReviewerProfileCatalog() {
+  return { profiles: structuredClone(REVIEWER_PROFILES), defaultRubric: structuredClone(DEFAULT_REVIEW_RUBRIC), roles: [...REVIEW_ROLES] };
+}
+
+export async function listReviewRounds(workspaceRoot, documentId) {
+  const reviews = (await loadProject(workspaceRoot)).reviews;
+  return documentId ? reviews.filter((item) => item.documentId === documentId) : reviews;
+}
+
+export async function createReviewRound(workspaceRoot, input = {}) {
+  const project = await loadProject(workspaceRoot);
+  if (!project.documents.some((item) => item.id === input.documentId)) throw problem('Document not found', 404);
+  const reviewers = Array.isArray(input.reviewers) ? input.reviewers.map(validateReviewer) : [];
+  const rubric = Array.isArray(input.rubric) ? input.rubric.map(validateRubric) : [];
+  if (!reviewers.length || reviewers.length > 8) throw problem('A review panel needs between 1 and 8 reviewers');
+  if (!rubric.length || rubric.length > 20) throw problem('A review rubric needs between 1 and 20 criteria');
+  if (new Set(reviewers.map((item) => item.id)).size !== reviewers.length) throw problem('Reviewer IDs must be unique');
+  if (new Set(rubric.map((item) => item.id)).size !== rubric.length) throw problem('Rubric IDs must be unique');
+  const timestamp = now();
+  const review = {
+    id: id('review'), documentId: input.documentId, name: clean(input.name) || 'Peer review round',
+    status: 'draft', provider: clean(input.provider) || 'mock', reviewers, rubric,
+    reports: [], items: [], synthesis: { summary: '', verdict: '', consensus: [], conflicts: [], priorities: [] },
+    createdAt: timestamp, updatedAt: timestamp,
+  };
+  if (!['mock', 'codex', 'claude-code', 'opencode', 'pi'].includes(review.provider)) throw problem('provider must be mock, codex, claude-code, opencode, or pi');
+  await updateProject(workspaceRoot, (draft) => draft.reviews.push(review));
+  return review;
+}
+
+function manuscriptSentences(content) {
+  return content.split(/(?<=[.!?。！？])\s+/).map((text) => text.trim()).filter((text) => text.length >= 20 && !/^\\(?:documentclass|usepackage)/.test(text));
+}
+
+function firstMatchingSentence(content, pattern) {
+  return manuscriptSentences(content).find((sentence) => pattern.test(sentence)) || manuscriptSentences(content)[0] || '';
+}
+
+export function generateMockPeerReview(content, reviewer, rubric) {
+  const rubricFor = (keyword, fallback = 0) => rubric.find((item) => item.id.toLowerCase().includes(keyword))?.id || rubric[fallback]?.id || rubric[0].id;
+  const lower = content.toLowerCase();
+  const items = [];
+  const add = (value) => items.push({ id: id('review_item'), ...value });
+  if (reviewer.role === 'methodology') {
+    const quote = firstMatchingSentence(content, /method|approach|algorithm|模型|方法|算法/i);
+    add({ rubricId: rubricFor('rigor'), kind: 'concern', category: 'method', severity: 'major', body: 'Clarify the design assumptions, comparison protocol, and threats to validity for the central method.', suggestedFix: '', quote });
+    add({ rubricId: rubricFor('evidence', 1), kind: 'strength', category: 'method', severity: 'info', body: 'The manuscript exposes a recognizable methodological contribution that can be evaluated explicitly.', suggestedFix: '', quote });
+  } else if (reviewer.role === 'statistics') {
+    const quote = firstMatchingSentence(content, /result|accuracy|significant|%|结果|准确|显著/i);
+    const hasStatistics = /confidence interval|standard deviation|p\s*[<=>]|effect size|置信区间|标准差|显著性/i.test(lower);
+    add({ rubricId: rubricFor('evidence', 1), kind: 'concern', category: 'evidence', severity: hasStatistics ? 'minor' : 'major', body: hasStatistics ? 'Report the statistical procedure and sample definition consistently for every quantitative comparison.' : 'Quantitative claims need uncertainty, sample sizes, and a justified statistical comparison.', suggestedFix: '', quote });
+  } else if (reviewer.role === 'writing') {
+    const imprecise = content.match(/\bvery\s+(?:important|useful|good|large)\b/i);
+    const quote = imprecise?.[0] || firstMatchingSentence(content, /conclusion|introduction|因此|本文|结论/i);
+    add({ rubricId: rubricFor('clarity', 2), kind: 'concern', category: 'style', severity: 'minor', body: 'Replace broad evaluative wording with a precise claim tied to the reported evidence.', suggestedFix: imprecise ? 'substantial' : '', quote });
+  } else if (reviewer.role === 'domain') {
+    const quote = firstMatchingSentence(content, /we (?:propose|present|show)|本文|我们提出|贡献/i);
+    add({ rubricId: rubricFor('evidence', 1), kind: 'concern', category: 'citation', severity: 'major', body: 'Position the central novelty against the closest domain-specific alternatives and state the practical boundary of the contribution.', suggestedFix: '', quote });
+  } else {
+    const quote = firstMatchingSentence(content, /experiment|implementation|dataset|实验|实现|数据/i);
+    const reproducible = /github|repository|code|seed|dataset|parameter|代码|仓库|随机种子|数据集|参数/i.test(lower);
+    add({ rubricId: rubricFor('reproducibility', 3), kind: 'concern', category: 'method', severity: reproducible ? 'minor' : 'major', body: reproducible ? 'Consolidate implementation details, versions, seeds, and data access instructions into a reproducibility checklist.' : 'Add code/data availability, parameter settings, environment versions, random seeds, and an executable reproduction protocol.', suggestedFix: '', quote });
+  }
+  const major = items.some((item) => SEVERITY_RANK[item.severity] >= SEVERITY_RANK.major && item.kind === 'concern');
+  return { summary: `${reviewer.name} identified ${items.filter((item) => item.kind === 'concern').length} actionable concern(s) from the ${reviewer.role} perspective.`, verdict: major ? 'major-revision' : 'minor-revision', confidence: 0.78, items };
+}
+
+function normalizeItem(item, reviewerId) {
+  return { ...item, id: item.id || id('review_item'), reviewerId };
+}
+
+function tokens(value) { return new Set(String(value || '').toLowerCase().match(/[\p{L}\p{N}]{3,}/gu) || []); }
+function similarity(left, right) {
+  const a = tokens(left); const b = tokens(right); if (!a.size || !b.size) return 0;
+  let shared = 0; a.forEach((token) => { if (b.has(token)) shared += 1; });
+  return shared / Math.min(a.size, b.size);
+}
+
+export function synthesizePeerReviews(reports) {
+  const items = reports.flatMap((report) => report.items || []);
+  const groups = [];
+  for (const item of items) {
+    const group = groups.find((candidate) => candidate.category === item.category
+      && ((item.quote && candidate.quote === item.quote) || similarity(candidate.body, item.body) >= 0.34));
+    if (group) { group.items.push(item); group.reviewerIds.add(item.reviewerId); }
+    else groups.push({ category: item.category, quote: item.quote, body: item.body, items: [item], reviewerIds: new Set([item.reviewerId]) });
+  }
+  const consensus = groups.filter((group) => group.reviewerIds.size >= 2 && group.items.every((item) => item.kind === group.items[0].kind)).map((group) => ({
+    id: id('consensus'), kind: group.items[0].kind, category: group.category, body: group.body,
+    itemIds: group.items.map((item) => item.id), reviewerIds: [...group.reviewerIds],
+  }));
+  const conflicts = groups.filter((group) => new Set(group.items.map((item) => item.kind)).size > 1
+    || new Set(group.items.map((item) => item.suggestedFix).filter(Boolean)).size > 1).map((group) => ({
+    id: id('conflict'), category: group.category, quote: group.quote,
+    description: 'Reviewers disagree on the assessment or proposed resolution for the same manuscript area.',
+    itemIds: group.items.map((item) => item.id), reviewerIds: [...group.reviewerIds],
+  }));
+  const priorities = items.filter((item) => item.kind === 'concern').sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]).slice(0, 12).map((item) => item.id);
+  const verdictCounts = Object.fromEntries(VERDICTS.map((verdict) => [verdict, reports.filter((report) => report.verdict === verdict).length]));
+  const verdict = [...VERDICTS].reverse().find((candidate) => verdictCounts[candidate]) || 'accept';
+  return {
+    summary: `${reports.length} independent report(s), ${items.length} finding(s), ${consensus.length} consensus cluster(s), and ${conflicts.length} conflict(s).`,
+    verdict, consensus, conflicts, priorities,
+  };
+}
+
+async function runOneReviewer(workspaceRoot, provider, content, reviewer, rubric, options, file = '') {
+  const startedAt = now();
+  const run = await createAgentRun(workspaceRoot, {
+    provider, operation: 'peer-review', status: provider === 'mock' ? 'queued' : 'running',
+    prompt: JSON.stringify({ reviewer, rubric }), input: JSON.stringify({ characters: content.length, reviewerId: reviewer.id }),
+    output: '', error: '', startedAt, finishedAt: '',
+  });
+  try {
+    const result = provider === 'mock' ? generateMockPeerReview(content, reviewer, rubric)
+      : await runAcademicReviewAgent(provider, {
+        content, reviewer, rubric,
+        workspace: file ? { file, start: 0, end: content.length } : null,
+      }, options);
+    const report = {
+      id: id('review_report'), reviewerId: reviewer.id, runId: run.id, status: 'complete',
+      summary: result.summary, verdict: result.verdict, confidence: result.confidence,
+      items: result.items.map((item) => normalizeItem(item, reviewer.id)), error: '', createdAt: now(),
+    };
+    await updateAgentRun(workspaceRoot, run.id, { status: 'complete', output: JSON.stringify({ ...result, agentMeta: result.agentMeta }), finishedAt: now() });
+    return report;
+  } catch (error) {
+    await updateAgentRun(workspaceRoot, run.id, { status: 'failed', error: agentFailureAudit(error), finishedAt: now() });
+    return { id: id('review_report'), reviewerId: reviewer.id, runId: run.id, status: 'failed', summary: '', verdict: 'reject', confidence: 0, items: [], error: error.message.slice(0, 4000), createdAt: now() };
+  }
+}
+
+export async function runReviewRound(workspaceRoot, reviewId, options = {}) {
+  let project = await loadProject(workspaceRoot);
+  let review = project.reviews.find((item) => item.id === reviewId);
+  if (!review) throw problem('Review round not found', 404);
+  if (review.status === 'running') throw problem('Review round is already running', 409);
+  const document = project.documents.find((item) => item.id === review.documentId);
+  if (!document) throw problem('Document not found', 404);
+  await syncDocumentStructure(workspaceRoot, document.file);
+  project = await loadProject(workspaceRoot);
+  review = project.reviews.find((item) => item.id === reviewId);
+  const currentDocument = project.documents.find((item) => item.id === review.documentId);
+  const file = sanitizePath(currentDocument.file, workspaceRoot);
+  if (!file) throw problem('Access denied', 403);
+  const content = await readFile(file, 'utf-8');
+  if (currentDocument.sourceHash !== hash(content)) throw problem('Document structure is stale', 409);
+  await updateProject(workspaceRoot, (draft) => {
+    const current = draft.reviews.find((item) => item.id === reviewId);
+    current.status = 'running'; current.reports = []; current.items = [];
+    current.synthesis = { summary: '', verdict: '', consensus: [], conflicts: [], priorities: [] }; current.updatedAt = now();
+  });
+  const controller = new AbortController();
+  options.signal?.addEventListener('abort', () => controller.abort(), { once: true });
+  if (review.provider !== 'mock') await materializeLibraries(workspaceRoot);
+  const reports = await Promise.all(review.reviewers.map((reviewer) => runOneReviewer(workspaceRoot, review.provider, content, reviewer, review.rubric, {
+    workspaceRoot, commands: options.commands || {}, signal: controller.signal,
+  }, currentDocument.file)));
+  const successful = reports.filter((report) => report.status === 'complete');
+  const synthesis = synthesizePeerReviews(successful);
+  const { result } = await updateProject(workspaceRoot, (draft) => {
+    const current = draft.reviews.find((item) => item.id === reviewId);
+    current.status = successful.length ? 'complete' : 'failed'; current.reports = reports;
+    current.items = successful.flatMap((report) => report.items); current.synthesis = synthesis; current.updatedAt = now();
+    return structuredClone(current);
+  });
+  return result;
+}
+
+function flattenNodes(document) {
+  const nodes = [];
+  const visit = (items) => (items || []).forEach((node) => { nodes.push(node); visit(node.children); });
+  visit(document.sections); return nodes;
+}
+
+function targetForItem(document, content, item) {
+  if (!item.quote) return { type: 'document', id: document.id, start: 0, end: 0, quote: '' };
+  const start = content.indexOf(item.quote); const end = start < 0 ? 0 : start + item.quote.length;
+  const node = start < 0 ? null : flattenNodes(document).filter((candidate) => candidate.sourceRange?.start <= start && candidate.sourceRange?.end >= end)
+    .sort((a, b) => (a.sourceRange.end - a.sourceRange.start) - (b.sourceRange.end - b.sourceRange.start))[0];
+  return { type: start < 0 ? 'document' : 'range', id: node?.id || document.id, start: Math.max(0, start), end, quote: start < 0 ? '' : item.quote };
+}
+
+export async function sendReviewItemsToRevision(workspaceRoot, reviewId, itemIds, title = '') {
+  const project = await loadProject(workspaceRoot);
+  const review = project.reviews.find((item) => item.id === reviewId);
+  if (!review) throw problem('Review round not found', 404);
+  if (review.status !== 'complete') throw problem('Only a completed review can enter revision planning', 409);
+  const selectedIds = Array.isArray(itemIds) && itemIds.length ? itemIds : review.synthesis.priorities;
+  const selected = review.items.filter((item) => selectedIds.includes(item.id) && item.kind === 'concern');
+  if (!selected.length) throw problem('Select at least one concern');
+  const document = project.documents.find((item) => item.id === review.documentId);
+  const file = sanitizePath(document.file, workspaceRoot); if (!file) throw problem('Access denied', 403);
+  const content = await readFile(file, 'utf-8');
+  const timestamp = now();
+  const annotations = selected.map((item, index) => ({
+    id: id('annotation'), documentId: document.id, order: index + 1, target: targetForItem(document, content, item),
+    category: item.category, severity: item.severity, body: item.body, suggestedFix: item.suggestedFix,
+    status: 'open', source: { type: 'reviewer', actor: review.reviewers.find((reviewer) => reviewer.id === item.reviewerId)?.name || item.reviewerId },
+    createdAt: timestamp, updatedAt: timestamp,
+  }));
+  await updateProject(workspaceRoot, (draft) => draft.annotations.push(...annotations));
+  const revision = await createRevisionPlan(workspaceRoot, {
+    documentId: document.id, annotationIds: annotations.map((item) => item.id), title: clean(title) || `${review.name} revision`,
+  });
+  return { annotations, revision };
+}

package/src/server/revise-workflow.js

@@ -0,0 +1,278 @@
+import { randomUUID } from 'crypto';
+import { readFile } from 'fs/promises';
+import { compile } from './latex.js';
+import { sanitizePath } from './security.js';
+import { loadProject, updateProject } from './project-store.js';
+import { createAgentRun, updateAgentRun } from './project-resources.js';
+import { syncDocumentStructure } from './document-structure.js';
+import { buildLibraryContext, composeMockParagraph } from './library-engine.js';
+import { runPaperGenerationAgent, validatePaperGenerationResponse } from './agent-adapters.js';
+import { agentFailureAudit } from './agent-errors.js';
+
+function now() { return new Date().toISOString(); }
+function id(prefix) { return `${prefix}_${randomUUID()}`; }
+function problem(message, status = 400) { const error = new Error(message); error.status = status; return error; }
+function clean(value) { return typeof value === 'string' ? value.trim() : ''; }
+
+function targetLocation(target = {}) {
+  if (target.type === 'range') return `characters ${target.start}–${target.end}`;
+  return target.type || 'document';
+}
+
+function decisionForAnnotation(revision, annotationId) {
+  return revision.changes.find((change) => change.annotationId === annotationId);
+}
+
+export function buildRevisionPackage(revision, annotations) {
+  const related = revision.annotationIds.map((annotationId) => annotations.find((item) => item.id === annotationId)).filter(Boolean);
+  const items = related.map((annotation, index) => {
+    const change = decisionForAnnotation(revision, annotation.id);
+    const status = change?.status || annotation.status;
+    let response;
+    if (['applied', 'accepted'].includes(status)) {
+      response = change?.after
+        ? `We addressed this comment by revising “${change.before}” to “${change.after}”.`
+        : 'We addressed this comment in the revised manuscript.';
+    } else if (status === 'rejected') response = 'We respectfully did not make this change; the rationale should be completed by the author.';
+    else if (status === 'deferred') response = 'This comment is deferred and remains to be addressed.';
+    else response = 'This comment remains open and requires an author response.';
+    return {
+      annotationId: annotation.id, order: annotation.order || index + 1, opinion: annotation.body,
+      response, status, location: targetLocation(annotation.target),
+    };
+  });
+  const changeList = revision.changes.map((change, index) => ({
+    changeId: change.id, annotationId: change.annotationId || '', order: index + 1, status: change.status,
+    location: targetLocation(change.target), before: change.before, after: change.after, reason: change.reason,
+  }));
+  return {
+    responseLetter: {
+      title: `Response to comments — ${revision.title}`,
+      introduction: 'We thank the reviewers for their constructive feedback. Responses and manuscript changes are listed point by point below.',
+      items,
+    },
+    changeList,
+  };
+}
+
+export async function generateRevisionPackage(workspaceRoot, revisionId) {
+  const { result } = await updateProject(workspaceRoot, (project) => {
+    const revision = project.revisions.find((item) => item.id === revisionId);
+    if (!revision) throw problem('Revision not found', 404);
+    const generated = buildRevisionPackage(revision, project.annotations);
+    if (revision.responseLetter) {
+      generated.responseLetter.introduction = revision.responseLetter.introduction;
+      const priorResponses = new Map(revision.responseLetter.items.map((item) => [item.annotationId, item.response]));
+      generated.responseLetter.items.forEach((item) => {
+        if (priorResponses.has(item.annotationId)) item.response = priorResponses.get(item.annotationId);
+      });
+    }
+    revision.responseLetter = generated.responseLetter;
+    revision.changeList = generated.changeList;
+    revision.updatedAt = now();
+    return { revision: structuredClone(revision), ...structuredClone(generated) };
+  });
+  return result;
+}
+
+export async function updateRevisionResponseLetter(workspaceRoot, revisionId, input = {}) {
+  const { result } = await updateProject(workspaceRoot, (project) => {
+    const revision = project.revisions.find((item) => item.id === revisionId);
+    if (!revision) throw problem('Revision not found', 404);
+    if (!revision.responseLetter) throw problem('Generate a response letter first', 409);
+    if (input.introduction !== undefined) {
+      if (typeof input.introduction !== 'string') throw problem('introduction must be a string');
+      revision.responseLetter.introduction = input.introduction;
+    }
+    if (Array.isArray(input.items)) {
+      for (const patch of input.items) {
+        const item = revision.responseLetter.items.find((candidate) => candidate.annotationId === patch.annotationId);
+        if (!item) throw problem(`Response item not found: ${patch.annotationId}`, 404);
+        if (typeof patch.response !== 'string' || !patch.response.trim()) throw problem('Each response must be non-empty');
+        item.response = patch.response;
+      }
+    }
+    revision.updatedAt = now();
+    return structuredClone(revision.responseLetter);
+  });
+  return result;
+}
+
+export async function verifyAppliedRevision(workspaceRoot, revisionId) {
+  const project = await loadProject(workspaceRoot);
+  const revision = project.revisions.find((item) => item.id === revisionId);
+  if (!revision) throw problem('Revision not found', 404);
+  if (revision.status !== 'applied') throw problem('Apply the revision before verification', 409);
+  const document = project.documents.find((item) => item.id === revision.documentId);
+  const file = sanitizePath(document.file, workspaceRoot);
+  if (!file) throw problem('Access denied', 403);
+  const compileResult = await compile(file, workspaceRoot);
+  const refreshed = await loadProject(workspaceRoot);
+  const unresolved = refreshed.annotations.filter((item) => item.documentId === document.id && !['resolved', 'rejected'].includes(item.status));
+  const verification = {
+    checkedAt: now(), compile: {
+      ok: compileResult.ok, engine: compileResult.engine || '', error: compileResult.ok ? '' : String(compileResult.error || '').slice(0, 4000),
+    },
+    unresolvedAnnotationIds: unresolved.map((item) => item.id),
+    complete: Boolean(compileResult.ok && unresolved.length === 0),
+  };
+  await updateProject(workspaceRoot, (draft) => {
+    const current = draft.revisions.find((item) => item.id === revisionId);
+    current.verification = verification; current.updatedAt = now();
+  });
+  return { verification, unresolved };
+}
+
+function escapeLatex(value) {
+  return String(value || '').replace(/\\/g, '\\textbackslash{}').replace(/([#$%&_{}])/g, '\\$1').replace(/~/g, '\\textasciitilde{}').replace(/\^/g, '\\textasciicircum{}');
+}
+
+function outlineContext(document) {
+  const lines = [];
+  for (const section of document.sections || []) {
+    lines.push(`SECTION: ${section.title}\nSummary: ${section.summary || ''}\nPrompt: ${section.prompt || ''}`);
+    for (const [index, paragraph] of (section.children || []).entries()) {
+      lines.push(`  PARAGRAPH ${index + 1}: ${paragraph.summary || ''}\n  Prompt: ${paragraph.prompt || ''}`);
+      for (const sentence of paragraph.children || []) if (sentence.intent) lines.push(`    Sentence intent: ${sentence.intent}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function composeMockPaper(project, document, libraries, libraryContext, instruction) {
+  const title = document.title || project.name || 'Generated Paper';
+  const sections = document.sections?.length ? document.sections : [
+    { title: 'Introduction', prompt: 'Present the problem, gap, and contributions.', children: [] },
+    { title: 'Methods', prompt: 'Describe the method and assumptions.', children: [] },
+    { title: 'Results', prompt: 'Report evidence and calibrated findings.', children: [] },
+    { title: 'Conclusion', prompt: 'Summarize contributions, limitations, and future work.', children: [] },
+  ];
+  const used = new Set();
+  const sectionLatex = sections.map((section) => {
+    const paragraphPrompts = section.children?.length
+      ? section.children.map((paragraph) => paragraph.prompt || paragraph.summary || paragraph.text)
+      : [section.prompt || section.summary || `Develop the ${section.title} section.`];
+    const paragraphs = paragraphPrompts.map((prompt) => {
+      const composed = composeMockParagraph(libraries, libraryContext, [instruction, prompt].filter(Boolean).join(' '));
+      composed.usedResourceIds.forEach((resourceId) => used.add(resourceId));
+      return escapeLatex(composed.draft);
+    });
+    return `\\section{${escapeLatex(section.title)}}\n${paragraphs.join('\n\n')}`;
+  }).join('\n\n');
+  const abstractGoal = clean(document.corePrompt) || clean(project.corePrompt) || clean(instruction) || 'Summarize the research problem, approach, evidence, and contribution.';
+  const latex = `\\documentclass{article}
+\\usepackage[utf8]{inputenc}
+\\usepackage{amsmath}
+\\title{${escapeLatex(title)}}
+\\author{}
+\\date{}
+
+\\begin{document}
+\\maketitle
+
+\\begin{abstract}
+${escapeLatex(`Draft objective: ${abstractGoal}`)}
+\\end{abstract}
+
+${sectionLatex}
+
+\\end{document}
+`;
+  return { summary: `Generated a complete draft with ${sections.length} section(s) from the structured writing context.`, latex, usedResourceIds: [...used] };
+}
+
+export async function generatePaperRevision(workspaceRoot, input = {}, options = {}) {
+  let project = await loadProject(workspaceRoot);
+  const document = project.documents.find((item) => item.id === input.documentId);
+  if (!document) throw problem('Document not found', 404);
+  await syncDocumentStructure(workspaceRoot, document.file);
+  project = await loadProject(workspaceRoot);
+  const currentDocument = project.documents.find((item) => item.id === input.documentId);
+  const file = sanitizePath(currentDocument.file, workspaceRoot);
+  if (!file) throw problem('Access denied', 403);
+  const original = await readFile(file, 'utf-8');
+  const instruction = clean(input.instruction);
+  if (!instruction && !clean(project.project.corePrompt) && !clean(currentDocument.corePrompt)) throw problem('Add a generation instruction or a core prompt');
+  const libraryContext = buildLibraryContext(project.libraries, {
+    query: [instruction, project.project.corePrompt, currentDocument.corePrompt].filter(Boolean).join(' '),
+    resourceIds: Array.isArray(input.resourceIds) ? input.resourceIds : [],
+  });
+  const provider = options.provider || 'mock';
+  const startedAt = now();
+  const run = await createAgentRun(workspaceRoot, {
+    provider, operation: 'generate-paper', status: provider === 'mock' ? 'queued' : 'running', prompt: instruction,
+    input: JSON.stringify({ documentId: currentDocument.id, providedResources: libraryContext.resources }), output: '', error: '', startedAt, finishedAt: '',
+  });
+  try {
+    const request = {
+      instruction,
+      projectContext: `Project prompt: ${project.project.corePrompt}\nDocument prompt: ${currentDocument.corePrompt}\nDocument summary: ${currentDocument.summary}`,
+      outlineContext: outlineContext(currentDocument), resourceContext: libraryContext.prompt, resourceIds: libraryContext.resourceIds,
+    };
+    const generated = provider === 'mock'
+      ? composeMockPaper(project.project, currentDocument, project.libraries, libraryContext, instruction)
+      : await runPaperGenerationAgent(provider, request, { workspaceRoot, commands: options.commands || {}, signal: options.signal });
+    const validation = validatePaperGenerationResponse(generated, libraryContext.resourceIds);
+    if (!validation.ok) throw problem(`Generated paper failed validation: ${validation.errors.join('; ')}`, 502);
+    await updateAgentRun(workspaceRoot, run.id, { status: 'complete', output: JSON.stringify({ summary: generated.summary, usedResourceIds: generated.usedResourceIds, characters: generated.latex.length, agentMeta: generated.agentMeta }), finishedAt: now() });
+    const timestamp = now();
+    const changeId = id('change');
+    const revision = {
+      id: id('revision'), documentId: currentDocument.id, file: currentDocument.file,
+      title: clean(input.title) || 'Generated full-paper draft', summary: generated.summary, status: 'review', annotationIds: [],
+      changes: [{
+        id: changeId, target: { type: 'range', id: currentDocument.id, start: 0, end: original.length, quote: original },
+        before: original, after: generated.latex, reason: 'Generate a complete paper from the project prompt, structured outline, element prompts, and writing libraries.',
+        status: 'proposed', executable: original !== generated.latex, dependsOn: [], conflictsWith: [],
+      }],
+      graph: { nodes: [changeId], edges: [] }, recoveryPoint: null, origin: 'paper-generation',
+      generation: { runId: run.id, instruction, providedResourceIds: libraryContext.resourceIds, usedResourceIds: generated.usedResourceIds },
+      createdAt: timestamp, updatedAt: timestamp,
+    };
+    await updateProject(workspaceRoot, (draft) => draft.revisions.push(revision));
+    return { revision, draft: generated.latex, runId: run.id, library: { mode: libraryContext.mode, providedResources: libraryContext.resources, usedResourceIds: generated.usedResourceIds } };
+  } catch (error) {
+    await updateAgentRun(workspaceRoot, run.id, { status: 'failed', error: agentFailureAudit(error), finishedAt: now() });
+    throw error;
+  }
+}
+
+export async function getWorkflowHistory(workspaceRoot, documentId) {
+  const project = await loadProject(workspaceRoot);
+  const events = [
+    ...project.revisions.filter((item) => !documentId || item.documentId === documentId).map((item) => ({ id: item.id, type: 'revision', status: item.status, title: item.title, at: item.updatedAt, detail: item.summary })),
+    ...project.reviews.filter((item) => !documentId || item.documentId === documentId).map((item) => ({ id: item.id, type: 'peer-review', status: item.status, title: item.name, at: item.updatedAt, detail: item.synthesis?.summary || '' })),
+    ...project.agentRuns.map((item) => ({ id: item.id, type: 'agent-run', status: item.status, title: `${item.provider} · ${item.operation}`, at: item.updatedAt, detail: item.error || '' })),
+  ].sort((a, b) => b.at.localeCompare(a.at));
+  return events;
+}
+
+function responseLetterMarkdown(revision) {
+  const letter = revision.responseLetter;
+  if (!letter) return '';
+  return `# ${letter.title}\n\n${letter.introduction}\n\n${letter.items.map((item) => `## Comment ${item.order}\n\n> ${item.opinion}\n\n**Response (${item.status}, ${item.location}):** ${item.response}`).join('\n\n')}`;
+}
+
+function changeListMarkdown(revision) {
+  const list = revision.changeList || buildRevisionPackage(revision, []).changeList;
+  return `# Change list — ${revision.title}\n\n${list.map((item) => `## Change ${item.order} — ${item.status}\n\n- Location: ${item.location}\n- Reason: ${item.reason}\n- Before: ${item.before || '(none)'}\n- After: ${item.after || '(none)'}`).join('\n\n')}`;
+}
+
+export async function buildWorkflowExport(workspaceRoot, documentId) {
+  const project = await loadProject(workspaceRoot);
+  const document = project.documents.find((item) => item.id === documentId);
+  if (!document) throw problem('Document not found', 404);
+  const file = sanitizePath(document.file, workspaceRoot); if (!file) throw problem('Access denied', 403);
+  const revisions = project.revisions.filter((item) => item.documentId === documentId);
+  return {
+    exportedAt: now(), project: project.project, document, source: await readFile(file, 'utf-8'),
+    annotations: project.annotations.filter((item) => item.documentId === documentId),
+    reviews: project.reviews.filter((item) => item.documentId === documentId), revisions,
+    agentRuns: project.agentRuns,
+    history: await getWorkflowHistory(workspaceRoot, documentId),
+    artifacts: revisions.map((revision) => ({
+      revisionId: revision.id, responseLetterMarkdown: responseLetterMarkdown(revision), changeListMarkdown: changeListMarkdown(revision),
+      recoveryPoint: revision.recoveryPoint,
+    })),
+  };
+}