From 4a2838ed6f6b991a49ad459dba21a9ca21b54cd9 Mon Sep 17 00:00:00 2001
From: Xule Lin <43122877+linxule@users.noreply.github.com>
Date: Sat, 10 Oct 2026 14:31:07 +0200
Subject: [PATCH 1/5] feat(export): snapshot-grounded analysis file builders

interviews.jsonl (exact text, the quotation source), interviews.csv,
profile_fields.csv and per-interview turn CSVs, plus a README that repeats
the Markdown export's consent/provider warning from the shared constant.
CSVs: UTF-8 BOM, CRLF, every cell through csvCell. Turn indexes match the
analysis citation numbering.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/lib/export/analysisFiles.ts       | 235 ++++++++++++++++++++++++++
 src/lib/export/transcriptsMarkdown.ts |  12 +-
 tests/unit/analysisFiles.test.ts      | 182 ++++++++++++++++++++
 3 files changed, 425 insertions(+), 4 deletions(-)
 create mode 100644 src/lib/export/analysisFiles.ts
 create mode 100644 tests/unit/analysisFiles.test.ts

diff --git a/src/lib/export/analysisFiles.ts b/src/lib/export/analysisFiles.ts
new file mode 100644
index 0000000..e3d8647
--- /dev/null
+++ b/src/lib/export/analysisFiles.ts
@@ -0,0 +1,235 @@
+// Portable, snapshot-only analysis views. Never reconstruct history from a live study.
+import type { StoredInterview } from '@/types';
+import { analysisStatus } from '@/lib/analysisState';
+import { csvCell } from '@/lib/csv';
+import { LANGUAGE_TAGS } from '@/lib/i18n/languages';
+import { AI_SHARING_WARNING, escapeMarkdownInline } from './transcriptsMarkdown';
+
+export const ANALYSIS_SCHEMA = 'openinterviewer.analysis.v1';
+export const DEFINITION_UNAVAILABLE = '(definition unavailable)';
+const iso = (timestamp: number) => new Date(timestamp).toISOString();
+
+export function analysisProfile(interview: StoredInterview) {
+  return {
+    fields: (interview.participantProfile?.fields ?? []).map(field => ({
+      fieldId: field.fieldId,
+      label: interview.collectionConfig?.profileSchema.find(definition => definition.id === field.fieldId)?.label ?? DEFINITION_UNAVAILABLE,
+      value: field.value,
+      status: field.status,
+    })),
+    context: interview.participantProfile?.rawContext,
+  };
+}
+
+export function analysisTurns(interview: StoredInterview) {
+  return interview.transcript.flatMap((message, index) => message.role === 'system' ? [] : [{
+    index: index + 1,
+    messageId: message.id,
+    role: message.role,
+    speaker: message.role === 'user' ? 'Participant' as const : 'Interviewer' as const,
+    timestamp: iso(message.timestamp),
+    offsetSeconds: (message.timestamp - interview.createdAt) / 1000,
+    text: message.content,
+  }]);
+}
+
+export function analysisInterview(interview: StoredInterview) {
+  const config = interview.collectionConfig;
+  return {
+    schema: ANALYSIS_SCHEMA,
+    study: {
+      id: interview.studyId, name: interview.studyName, revision: interview.studyRevision,
+      researchQuestion: config?.researchQuestion, coreQuestions: config?.coreQuestions,
+      topicAreas: config?.topicAreas, interviewLanguages: config?.interviewLanguages,
+    },
+    interview: {
+      id: interview.id, status: interview.status,
+      createdAt: iso(interview.createdAt), completedAt: iso(interview.completedAt),
+      durationMinutes: (interview.completedAt - interview.createdAt) / 60_000,
+      language: interview.interviewLanguage,
+      languageTag: interview.interviewLanguage ? LANGUAGE_TAGS[interview.interviewLanguage] : undefined,
+      voiceInput: config ? config.voiceInput ?? 'off' : undefined,
+    },
+    consent: {
+      providerCommitment: interview.providerCommitment,
+      conductedBy: { provider: interview.conductedByProvider, model: interview.conductedByModel },
+      transport: interview.consentTransport ?? 'direct',
+      consentHash: interview.consentHash,
+      consentAcceptedAt: interview.consentAcceptedAt === undefined ? undefined : iso(interview.consentAcceptedAt),
+    },
+    analysis: {
+      status: analysisStatus(interview), provider: interview.aiProvider, model: interview.aiModel,
+      transport: interview.aiTransport ?? 'direct',
+      bottomLine: interview.synthesis?.bottomLine, themes: interview.synthesis?.themes,
+    },
+    profile: analysisProfile(interview),
+    turns: analysisTurns(interview),
+  };
+}
+
+export function analysisJsonLine(interview: StoredInterview): string {
+  return `${JSON.stringify(analysisInterview(interview))}\n`;
+}
+
+/** CSV record separators AND embedded text newlines are CRLF; JSONL retains exact text. */
+export function analysisCsvRow(cells: readonly unknown[]): string {
+  return cells.map(cell => csvCell(cell === undefined || cell === null ? '' : String(cell).replace(/\r\n?|\n/g, '\r\n'))).join(',') + '\r\n';
+}
+export const analysisCsvHeader = (cells: readonly string[]) => '\uFEFF' + analysisCsvRow(cells);
+
+// The same descriptors generate the CSV and its data dictionary.
+const INTERVIEW_COLUMNS = [
+  ['schema', 'schema', 'Version identifier: openinterviewer.analysis.v1.'],
+  ['study_id', 'study.id', 'Stored study ID.'],
+  ['study_name', 'study.name', 'Study name recorded with this interview.'],
+  ['study_revision', 'study.revision', 'Collection revision, not the current study revision.'],
+  ['research_question', 'study.researchQuestion', 'Research question in collectionConfig.'],
+  ['core_questions', 'study.coreQuestions', 'Collection core questions; JSON array in this CSV cell.'],
+  ['topic_areas', 'study.topicAreas', 'Collection topic areas; JSON array in this CSV cell.'],
+  ['interview_languages', 'study.interviewLanguages', 'Offered language codes in collectionConfig; JSON array in this CSV cell.'],
+  ['interview_id', 'interview.id', 'Stored interview ID.'],
+  ['status', 'interview.status', 'Stored interview status: in_progress or completed.'],
+  ['created_at_utc', 'interview.createdAt', 'Start time, ISO 8601 UTC including milliseconds.'],
+  ['completed_at_utc', 'interview.completedAt', 'Completion time, ISO 8601 UTC including milliseconds.'],
+  ['duration_minutes', 'interview.durationMinutes', 'Elapsed minutes: (completedAt - createdAt) / 60000, not rounded.'],
+  ['language', 'interview.language', 'Recorded participant language code; absent is not inferred as English.'],
+  ['language_tag', 'interview.languageTag', 'BCP-47 tag from the shared language registry (zh becomes zh-Hans).'],
+  ['voice_input', 'interview.voiceInput', 'Mode offered: off, browser or installation, not evidence that voice was used. A known snapshot with no setting means off.'],
+  ['provider_commitment', 'consent.providerCommitment', 'Recorded promise: fixed or may-change; absent means not recorded.'],
+  ['conducted_by_provider', 'consent.conductedBy.provider', 'Provider selected for the conversation, not synthesis.'],
+  ['conducted_by_model', 'consent.conductedBy.model', 'Model requested for the conversation, not reported execution provenance.'],
+  ['consent_transport', 'consent.transport', 'Transport disclosed at consent: cloudflare-gateway, or direct when absent in storage.'],
+  ['consent_hash', 'consent.consentHash', 'Recorded hash of the accepted consent text.'],
+  ['consent_accepted_at_utc', 'consent.consentAcceptedAt', 'Recorded consent acceptance time, ISO 8601 UTC.'],
+  ['analysis_status', 'analysis.status', 'pending, running, complete or failed; legacy status follows the existing analysisStatus helper.'],
+  ['analysis_provider', 'analysis.provider', 'Recorded synthesis provider (aiProvider).'],
+  ['analysis_model', 'analysis.model', 'Recorded synthesis model (aiModel).'],
+  ['analysis_transport', 'analysis.transport', 'Synthesis transport: cloudflare-gateway, or direct when absent in storage; not proof a synthesis ran.'],
+  ['bottom_line', 'analysis.bottomLine', 'Saved synthesis bottom line; missing without synthesis.'],
+  ['themes', 'analysis.themes', 'CSV: theme names joined with "; ". JSONL: original theme objects, including frequency and any evidence/evidenceRefs.'],
+  ['profile_context', 'profile.context', 'Saved participantProfile.rawContext, not raw transcript text.'],
+] as const;
+
+export type ProfileColumn = { fieldId: string; label: string; createdAt: number; interviewId: string };
+export type ProfileColumns = Map<string, ProfileColumn>;
+
+/** Across studies/revisions, newest collection time wins; ties use descending interview ID. */
+export function collectProfileColumns(columns: ProfileColumns, interview: StoredInterview): void {
+  const definitions = new Map(interview.collectionConfig?.profileSchema.map(field => [field.id, field.label]));
+  const fieldIds = new Set([...definitions.keys(), ...(interview.participantProfile?.fields ?? []).map(field => field.fieldId)]);
+  for (const fieldId of fieldIds) {
+    const previous = columns.get(fieldId);
+    const candidate = { fieldId, label: definitions.get(fieldId) ?? DEFINITION_UNAVAILABLE, createdAt: interview.createdAt, interviewId: interview.id };
+    if (!previous || candidate.createdAt > previous.createdAt
+      || (candidate.createdAt === previous.createdAt && candidate.interviewId > previous.interviewId)) {
+      columns.set(fieldId, candidate);
+    }
+  }
+}
+export function sortedProfileColumns(columns: ProfileColumns): ProfileColumn[] {
+  return [...columns.values()].sort((a, b) => a.fieldId < b.fieldId ? -1 : a.fieldId > b.fieldId ? 1 : 0);
+}
+/** Pack small dictionary fragments without retaining an export-wide header or README. */
+export function* analysisTextChunks(parts: Iterable<string>): Generator<string> {
+  let chunk = '';
+  for (const part of parts) {
+    if (chunk.length + part.length > 32 * 1024) { yield chunk; chunk = ''; }
+    chunk += part;
+  }
+  if (chunk) yield chunk;
+}
+export function* analysisInterviewsHeaderParts(columns: ProfileColumn[]): Generator<string> {
+  yield analysisCsvHeader(INTERVIEW_COLUMNS.map(column => column[0])).slice(0, -2);
+  for (const column of columns) yield ',' + analysisCsvRow([`profile:${column.fieldId} (${column.label})`]).slice(0, -2);
+  yield '\r\n';
+}
+export function analysisInterviewsHeader(columns: ProfileColumn[]): string {
+  return [...analysisInterviewsHeaderParts(columns)].join('');
+}
+export function analysisInterviewsRow(interview: StoredInterview, columns: ProfileColumn[]): string {
+  const record = analysisInterview(interview);
+  const cells = INTERVIEW_COLUMNS.map(([, path]) => {
+    let value: unknown = record;
+    for (const key of path.split('.')) value = (value as Record<string, unknown> | undefined)?.[key];
+    if (path === 'analysis.themes') return record.analysis.themes?.map(theme => theme.theme).join('; ');
+    return Array.isArray(value) ? JSON.stringify(value) : value;
+  });
+  const fields = new Map(record.profile.fields.map(field => [field.fieldId, field.value]));
+  return analysisCsvRow([...cells, ...columns.map(column => fields.get(column.fieldId))]);
+}
+
+export const TURN_COLUMNS = ['study_id', 'interview_id', 'turn_index', 'message_id', 'role', 'speaker', 'timestamp_utc', 'offset_s', 'language', 'text'];
+export function analysisTurnsCsv(interview: StoredInterview): string {
+  return analysisCsvHeader(TURN_COLUMNS) + analysisTurns(interview).map(turn => analysisCsvRow([
+    interview.studyId, interview.id, turn.index, turn.messageId, turn.role, turn.speaker,
+    turn.timestamp, turn.offsetSeconds, interview.interviewLanguage, turn.text,
+  ])).join('');
+}
+export const analysisTurnsName = (position: number) => `analysis/turns/${String(position + 1).padStart(3, '0')}.csv`;
+export const PROFILE_COLUMNS = ['interview_id', 'study_revision', 'field_id', 'label_at_collection', 'value', 'status'];
+export function analysisProfileRows(interview: StoredInterview): string {
+  return analysisProfile(interview).fields.map(field => analysisCsvRow([
+    interview.id, interview.studyRevision, field.fieldId, field.label, field.value, field.status,
+  ])).join('');
+}
+
+export function analysisReadme(columns: ProfileColumn[]): string {
+  return [...analysisReadmeParts(columns)].join('');
+}
+export function* analysisReadmeParts(columns: ProfileColumn[]): Generator<string> {
+  yield `# Analysis files
+
+${AI_SHARING_WARNING}
+
+These views use each interview's own saved collectionConfig and consent/provider records, never today's study configuration. See consent in JSONL for what was recorded for each participant. Unknown optional values are omitted from JSONL and blank in CSV; explicit null profile values remain null in JSONL. Missing history is not reconstructed. All timestamps are ISO UTC.
+
+## Files and encoding
+
+- interviews.jsonl: one object per interview, schema ${ANALYSIS_SCHEMA}. UTF-8, no BOM, LF record endings. JSON escapes decode to the EXACT stored turn text, including original line endings.
+- interviews.csv: one row per interview, followed by a column for every observed profile field ID across the export.
+- turns/NNN.csv: one turn CSV per interview, numbered in the same export order as the top-level NNN records. Sharded instead of turns.csv to bound Worker memory. Each shard has its own header and BOM.
+- profile_fields.csv: one row per saved profile field value, preserving the label at collection.
+- README.md: this data dictionary and sharing guidance.
+
+All CSVs are UTF-8 with BOM, CRLF record endings and quoted cells. Embedded text newlines are normalized to CRLF. Every cell, including headers, passes the spreadsheet formula-injection guard. CSV text cells may start with an added apostrophe (') for that guard: use the JSONL for verbatim quotes, not CSV.
+
+## interviews.csv columns and JSONL fields
+
+${INTERVIEW_COLUMNS.map(([name, path, description]) => `- ${name} → ${path}: ${description}`).join('\n')}
+
+Dynamic columns have the header profile:<fieldId> (<newest label>), ordered by field ID (code-unit order). One column per field ID observed in saved profile values or collectionConfig.profileSchema, even across studies: do not assume the same ID has the same meaning across studies. The newest interview by createdAt supplies the label from its own collectionConfig; ties use descending interview ID. Missing definitions use "${DEFINITION_UNAVAILABLE}" rather than a current or older label. Values are preserved regardless of extraction status; blank conflates absent, null and empty text in CSV. Use JSONL or profile_fields.csv for status and historical labels.
+
+`;
+  for (const column of columns) yield `- ${escapeMarkdownInline(`profile:${column.fieldId} (${column.label})`)}: saved value for field ID ${escapeMarkdownInline(column.fieldId)}.\n`;
+  yield `
+
+## JSONL nested structures
+
+- study, interview, consent, analysis and profile: grouped fields defined above. consent.conductedBy groups the recorded conversation provider and model.
+- profile.fields: saved profile values, each with fieldId (schema ID), label (definition in this interview's collectionConfig, or "${DEFINITION_UNAVAILABLE}"), value (string or null), status (pending, extracted, vague or refused). profile.context is rawContext.
+- analysis.themes[]: theme (name), frequency (saved count), optional evidence (legacy free text), optional evidenceRefs (citation claims). Each ref has quote (claimed excerpt), turnIndex (1-based full transcript coordinate), and optional interviewId. These are claims, not verified interpretations.
+- turns[]: index, messageId, role, speaker, timestamp, offsetSeconds and text, defined below. System messages are excluded, not renumbered.
+
+## Turn CSV columns (JSONL turns field in parentheses)
+
+- study_id: containing study.id.
+- interview_id: containing interview.id.
+- turn_index (index): 1-based position in the FULL stored transcript, matching analysis citation numbering (EvidenceRef.turnIndex). System messages are skipped without reusing their index, so gaps are intentional.
+- message_id (messageId): stored message.id.
+- role (role): stored user or ai.
+- speaker (speaker): Participant for user; Interviewer for ai.
+- timestamp_utc (timestamp): message.timestamp as ISO UTC.
+- offset_s (offsetSeconds): (message.timestamp - interview.createdAt) / 1000, not rounded; may be negative.
+- language: containing interview.language, blank if unrecorded.
+- text (text): message.content; exact in JSONL, guarded and newline-normalized in CSV.
+
+## profile_fields.csv columns
+
+- interview_id: containing interview.id.
+- study_revision: containing study.revision (collection revision).
+- field_id: profile.fields[].fieldId.
+- label_at_collection: profile.fields[].label from this interview's snapshot, not the newest label.
+- value: profile.fields[].value; null becomes blank.
+- status: profile.fields[].status, including non-extracted values.
+`;
+}
diff --git a/src/lib/export/transcriptsMarkdown.ts b/src/lib/export/transcriptsMarkdown.ts
index 37609e1..501212f 100644
--- a/src/lib/export/transcriptsMarkdown.ts
+++ b/src/lib/export/transcriptsMarkdown.ts
@@ -12,6 +12,13 @@ import type { StoredInterview, StoredStudy, StudyConfig } from '@/types';
 import { PROVIDER_MODELS, PROVIDER_OPTIONS } from '@/lib/providerRegistry';
 import { LANGUAGE_ENGLISH_NAMES, LANGUAGE_NATIVE_NAMES } from '@/lib/i18n/languages';
 
+export const AI_SHARING_WARNING = [
+    '> **Before sharing this file with an AI tool:** each interview below records what its',
+    '> participant was told about the AI that would handle their responses. Where a participant',
+    '> was told the study uses only one provider and model, sending this file to a different AI',
+    '> service may break that promise.',
+].join('\n');
+
 export const TRANSCRIPTS_MARKDOWN_CONTENT_TYPE = 'text/markdown; charset=utf-8';
 
 const COMPLETE_MARKER_PREFIX = '<!-- openinterviewer-export complete: ';
@@ -103,10 +110,7 @@ export function transcriptsMarkdownHeader(study: StoredStudy, count: number, exp
     `- Exported: ${isoUtc(exportedAt.getTime())}`,
     `- Interviews: ${count}`,
     '',
-    '> **Before sharing this file with an AI tool:** each interview below records what its',
-    '> participant was told about the AI that would handle their responses. Where a participant',
-    '> was told the study uses only one provider and model, sending this file to a different AI',
-    '> service may break that promise.',
+    AI_SHARING_WARNING,
     '',
     'Transcript text is quoted exactly as saved. Times are UTC.',
     '',
diff --git a/tests/unit/analysisFiles.test.ts b/tests/unit/analysisFiles.test.ts
new file mode 100644
index 0000000..1bae88a
--- /dev/null
+++ b/tests/unit/analysisFiles.test.ts
@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'vitest';
+import {
+  analysisCsvHeader, analysisCsvRow, analysisInterview, analysisInterviewsHeader, analysisInterviewsRow,
+  analysisJsonLine, analysisProfileRows, analysisReadme, analysisTurnsCsv, analysisTurnsName,
+  collectProfileColumns, DEFINITION_UNAVAILABLE, PROFILE_COLUMNS, sortedProfileColumns, type ProfileColumns,
+} from '@/lib/export/analysisFiles';
+import { AI_SHARING_WARNING, transcriptsMarkdownHeader } from '@/lib/export/transcriptsMarkdown';
+import { interviewTranscriptMarkdown } from '@/lib/export/interviewExport';
+import { resolveEvidenceRef } from '@/lib/evidence';
+import { makeStoredInterview, makeStoredStudy, makeStudyConfig } from '../fixtures/models';
+import { INTERVIEW_LANGUAGES, LANGUAGE_TAGS } from '@/lib/i18n/languages';
+
+// Parse quoted multiline CSV, as an importing spreadsheet would (no formula evaluation).
+function parseCsv(csv: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [], cell = '', quoted = false;
+  const text = csv.replace(/^\uFEFF/, '');
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"') {
+      if (quoted && text[i + 1] === '"') { cell += '"'; i++; }
+      else quoted = !quoted;
+    } else if (!quoted && ch === ',') { row.push(cell); cell = ''; }
+    else if (!quoted && ch === '\r' && text[i + 1] === '\n') {
+      row.push(cell); rows.push(row); row = []; cell = ''; i++;
+    } else cell += ch;
+  }
+  return rows;
+}
+
+const base = Date.UTC(2026, 9, 10, 12);
+function fixture() {
+  return makeStoredInterview({
+    id: 'iv-1', studyId: 'study-1', studyName: '研究', studyRevision: 3,
+    createdAt: base, completedAt: base + 90_500, status: 'completed',
+    collectionConfig: makeStudyConfig({ interviewLanguages: ['zh', 'en', 'fr'], voiceInput: 'installation' }),
+    interviewLanguage: 'zh', providerCommitment: 'fixed', conductedByProvider: 'openai', conductedByModel: 'fixture-conversation',
+    consentTransport: 'cloudflare-gateway', consentHash: 'a'.repeat(64), consentAcceptedAt: base - 1000,
+    aiProvider: 'gemini', aiModel: 'fixture-synthesis', aiTransport: 'cloudflare-gateway',
+    participantProfile: { id: 'p', fields: [
+      { fieldId: 'role', value: '=SUM(1,2)\n研究 "角色"', status: 'extracted' },
+      { fieldId: 'missing', value: null, status: 'refused' },
+    ], rawContext: '@context', timestamp: base },
+    transcript: [
+      { id: 's', role: 'system', timestamp: base, content: 'Not an interview turn' },
+      { id: 'a', role: 'ai', timestamp: base + 500, content: '你好，做什么？' },
+      { id: 'u', role: 'user', timestamp: base + 1200, content: '=研究, "引文"\r\n第二行\n第三行\r尾行' },
+    ],
+    synthesis: { bottomLine: '+insight', themes: [{ theme: '主题一', frequency: 1 }, { theme: '主题二', frequency: 2, evidenceRefs: [{ quote: '研究', turnIndex: 3 }] }],
+      statedPreferences: [], revealedPreferences: [], contradictions: [], keyInsights: [] },
+  });
+}
+
+describe('analysis file builders', () => {
+  it('projects only recorded collection and consent data, distinguishing conducting from analysis provenance', () => {
+    const interview = fixture();
+    const record = analysisInterview(interview);
+    expect(record.study).toEqual({ id: 'study-1', name: '研究', revision: 3,
+      researchQuestion: interview.collectionConfig!.researchQuestion, coreQuestions: interview.collectionConfig!.coreQuestions,
+      topicAreas: interview.collectionConfig!.topicAreas, interviewLanguages: ['zh', 'en', 'fr'] });
+    expect(record.interview).toEqual({ id: 'iv-1', status: 'completed', createdAt: '2026-10-10T12:00:00.000Z', completedAt: '2026-10-10T12:01:30.500Z', durationMinutes: 90.5 / 60, language: 'zh', languageTag: 'zh-Hans', voiceInput: 'installation' });
+    expect(record.consent).toEqual({ providerCommitment: 'fixed', conductedBy: { provider: 'openai', model: 'fixture-conversation' }, transport: 'cloudflare-gateway', consentHash: 'a'.repeat(64), consentAcceptedAt: '2026-10-10T11:59:59.000Z' });
+    expect(record.analysis).toEqual({ status: 'complete', provider: 'gemini', model: 'fixture-synthesis', transport: 'cloudflare-gateway', bottomLine: '+insight', themes: interview.synthesis!.themes });
+    expect(record.profile.context).toBe('@context');
+  });
+
+  it('JSONL has LF and no BOM, preserving exact text including mixed embedded line endings and CJK', () => {
+    const interview = fixture();
+    const line = analysisJsonLine(interview);
+    expect(line.charCodeAt(0)).not.toBe(0xfeff);
+    expect(line.endsWith('\n')).toBe(true);
+    expect(line.split('\n')).toHaveLength(2);
+    expect(line).not.toContain('\r');
+    const parsed = JSON.parse(line);
+    expect(parsed.schema).toBe('openinterviewer.analysis.v1');
+    expect(parsed.turns[1].text).toBe(interview.transcript[2].content);
+    expect(parsed.profile.fields[1].value).toBeNull();
+  });
+
+  it('CSV and JSONL preserve the full-transcript evidence/citation index across a system message', () => {
+    const interview = fixture();
+    interview.transcript[2].content = '研究 participants said this';
+    const json = JSON.parse(analysisJsonLine(interview));
+    const csv = parseCsv(analysisTurnsCsv(interview));
+    expect(json.turns.map((turn: { index: number }) => turn.index)).toEqual([2, 3]);
+    expect(csv.slice(1).map(row => Number(row[2]))).toEqual([2, 3]);
+    const ref = { quote: interview.transcript[2].content, turnIndex: Number(csv[2][2]) };
+    expect(resolveEvidenceRef(ref, interview.transcript)).toMatchObject({ status: 'verified', turnIndex: json.turns[1].index });
+    expect(csv[2]).toEqual(['study-1', 'iv-1', '3', 'u', 'user', 'Participant', '2026-10-10T12:00:01.200Z', '1.2', 'zh', interview.transcript[2].content]);
+    expect(analysisTurnsName(0)).toBe('analysis/turns/001.csv');
+    expect(analysisTurnsName(499)).toBe('analysis/turns/500.csv');
+  });
+
+  it('guards every CSV cell including headers; quotes commas, quotes, CJK and CRLF with a UTF-8 BOM', () => {
+    const cells = ['=calc', ' +calc', '-1', '@fn', '\tfoo', '\nbar', '研究,"引文"'];
+    const csv = analysisCsvHeader(cells) + analysisCsvRow(cells);
+    expect([...new TextEncoder().encode(csv).slice(0, 3)]).toEqual([239, 187, 191]);
+    expect(csv.replace(/\r\n/g, '')).not.toMatch(/[\r\n]/);
+    const parsed = parseCsv(csv);
+    expect(parsed[0]).toEqual(parsed[1]);
+    expect(parsed[0]).toEqual(["'=calc", "' +calc", "'-1", "'@fn", "'\tfoo", "'\r\nbar", '研究,"引文"']);
+    const turns = analysisTurnsCsv(fixture());
+    expect(parseCsv(turns)[2][9]).toBe("'=研究, \"引文\"\r\n第二行\r\n第三行\r\n尾行");
+  });
+
+  it('uses newest labels for wide headers and historical labels in long rows, regardless of input order', () => {
+    const newer = fixture();
+    const older = fixture();
+    older.id = 'old'; older.createdAt -= 1000; older.studyRevision = 2;
+    older.collectionConfig!.profileSchema[0].label = '旧角色';
+    older.participantProfile.fields[0].value = '以前';
+    const columns: ProfileColumns = new Map();
+    collectProfileColumns(columns, older); collectProfileColumns(columns, newer);
+    const sorted = sortedProfileColumns(columns);
+    const header = parseCsv(analysisInterviewsHeader(sorted))[0];
+    expect(header.slice(-2)).toEqual([`profile:missing (${DEFINITION_UNAVAILABLE})`, 'profile:role (Current Role)']);
+    const row = parseCsv(analysisInterviewsRow(newer, sorted))[0];
+    expect(row[header.indexOf('themes')]).toBe('主题一; 主题二');
+    expect(row[header.indexOf('core_questions')]).toBe(JSON.stringify(newer.collectionConfig!.coreQuestions));
+    expect(row[header.indexOf('bottom_line')]).toBe("'+insight");
+    expect(row.at(-1)).toBe("'=SUM(1,2)\r\n研究 \"角色\"");
+    const long = parseCsv(analysisCsvHeader(PROFILE_COLUMNS) + analysisProfileRows(older) + analysisProfileRows(newer));
+    expect(long[1]).toEqual(['old', '2', 'role', '旧角色', '以前', 'extracted']);
+    expect(long[4]).toEqual(['iv-1', '3', 'missing', DEFINITION_UNAVAILABLE, '', 'refused']);
+    const reverse: ProfileColumns = new Map();
+    collectProfileColumns(reverse, newer); collectProfileColumns(reverse, older);
+    expect(sortedProfileColumns(reverse)).toEqual(sorted);
+    const tie = fixture(); tie.id = 'z'; tie.collectionConfig!.profileSchema[0].label = 'Tie winner';
+    collectProfileColumns(columns, tie);
+    expect(columns.get('role')!.label).toBe('Tie winner');
+  });
+
+  it('includes schema-only field IDs with blank wide values, without inventing long-form values', () => {
+    const interview = fixture();
+    interview.collectionConfig!.profileSchema.push({ id: 'not-answered', label: 'New unanswered question', required: false, extractionHint: '' });
+    const columns: ProfileColumns = new Map();
+    collectProfileColumns(columns, interview);
+    const sorted = sortedProfileColumns(columns);
+    expect(parseCsv(analysisInterviewsHeader(sorted))[0]).toContain('profile:not-answered (New unanswered question)');
+    expect(parseCsv(analysisInterviewsRow(interview, sorted))[0].at(-2)).toBe('');
+    expect(analysisProfileRows(interview)).not.toContain('not-answered');
+  });
+
+  it('never backfills absent snapshot, language, revision, consent or execution provenance', () => {
+    const interview = makeStoredInterview({ createdAt: base, completedAt: base, participantProfile: fixture().participantProfile });
+    const record = JSON.parse(analysisJsonLine(interview));
+    expect(record.study).toEqual({ id: 'study-1', name: 'Study 1' });
+    expect(record.interview).not.toHaveProperty('voiceInput');
+    expect(record.interview).not.toHaveProperty('language');
+    expect(record.consent).toEqual({ conductedBy: {}, transport: 'direct' });
+    expect(record.analysis).toEqual({ status: 'pending', transport: 'direct' });
+    expect(record.profile.fields.every((field: { label: string }) => field.label === DEFINITION_UNAVAILABLE)).toBe(true);
+    interview.collectionConfig = makeStudyConfig();
+    expect(analysisInterview(interview).interview.voiceInput).toBe('off');
+    interview.collectionConfig.voiceInput = 'browser';
+    expect(analysisInterview(interview).interview.voiceInput).toBe('browser');
+  });
+
+  it.each(INTERVIEW_LANGUAGES)('exports the recorded %s language and its shared BCP-47 tag', language => {
+    const interview = fixture(); interview.interviewLanguage = language;
+    expect(analysisInterview(interview).interview).toMatchObject({ language, languageTag: LANGUAGE_TAGS[language] });
+    expect(parseCsv(analysisTurnsCsv(interview))[1][8]).toBe(language);
+  });
+
+  it('README reuses the exact Markdown sharing warning and defines all static CSV columns', () => {
+    const readme = analysisReadme([]);
+    expect(readme).toContain(AI_SHARING_WARNING);
+    expect(transcriptsMarkdownHeader(makeStoredStudy(), 1, new Date(base))).toContain(AI_SHARING_WARNING);
+    for (const header of [analysisInterviewsHeader([]), analysisCsvHeader(PROFILE_COLUMNS), analysisTurnsCsv(fixture())]) {
+      for (const column of parseCsv(header)[0]) expect(readme).toContain(column);
+    }
+    expect(readme).toContain('apostrophe');
+    expect(readme).toContain('FULL stored transcript');
+    expect(readme).toContain('newest interview by createdAt');
+  });
+
+  it('ZIP Markdown dates do not use the server locale', () => {
+    const text = interviewTranscriptMarkdown(fixture());
+    expect(text).toContain('Date: 2026-10-10T12:00:00.000Z');
+    expect(text).toContain('[2026-10-10T12:00:01.200Z] PARTICIPANT:');
+  });
+});

From 26e2147916b55a5f686120060372d937971c03a6 Mon Sep 17 00:00:00 2001
From: Xule Lin <43122877+linxule@users.noreply.github.com>
Date: Sat, 10 Oct 2026 14:31:07 +0200
Subject: [PATCH 2/5] feat(export): stream analysis entries in the Node and
 Durable ZIP exports

The ZIP writer accepts chunked entries with incremental CRC and size checks,
so the Worker streams the combined files instead of holding rows; turns are
sharded per interview (a single table's bound is ~830 MiB at the 500-interview
cap). The Durable path rereads the same export sequence and still verifies it
before the closing records. Per-interview Markdown dates are now ISO UTC.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/app/api/interviews/export/route.ts | 12 ++++++-
 src/lib/export/interviewExport.ts      | 47 ++++++++++++++++++++------
 src/lib/export/zipStream.ts            | 42 +++++++++++++++--------
 tests/unit/api.export.durable.test.ts  | 43 +++++++++++++++++++----
 tests/unit/api.export.scoped.test.ts   | 34 ++++++++++++++++---
 tests/unit/zipStream.test.ts           | 39 ++++++++++++++++++---
 tests/workers/exports.test.ts          | 25 ++++++++++----
 7 files changed, 195 insertions(+), 47 deletions(-)

diff --git a/src/app/api/interviews/export/route.ts b/src/app/api/interviews/export/route.ts
index 5de5a4d..6e89fbd 100644
--- a/src/app/api/interviews/export/route.ts
+++ b/src/app/api/interviews/export/route.ts
@@ -27,6 +27,7 @@ import {
   MAX_OWNED_STUDIES,
 } from '@/lib/ownedStudies';
 import JSZip from 'jszip';
+import { analysisCsvHeader, analysisInterviewsHeader, analysisInterviewsRow, analysisJsonLine, analysisProfileRows, analysisReadme, analysisTurnsCsv, analysisTurnsName, collectProfileColumns, PROFILE_COLUMNS, sortedProfileColumns, type ProfileColumns } from '@/lib/export/analysisFiles';
 import { StoredInterview, StoredAggregateSynthesis, type StoredStudy } from '@/types';
 import { logRequestFailure } from '@/lib/requestLog';
 import {
@@ -116,6 +117,8 @@ async function buildExportResponse(
   beforeReturn?: () => Promise<Response | null>,
 ): Promise<Response> {
   const zip = new JSZip();
+  zip.folder('analysis/turns');
+  const columns: ProfileColumns = new Map();
 
   // Entry names and contents come from the builders the Cloudflare stream
   // uses, so the two archives cannot drift apart.
@@ -123,6 +126,8 @@ async function buildExportResponse(
     const baseName = interviewEntryBaseName(index, interview);
     zip.file(`${baseName}.json`, interviewJson(interview));
     zip.file(`${baseName}.md`, interviewTranscriptMarkdown(interview));
+    zip.file(analysisTurnsName(index), analysisTurnsCsv(interview));
+    collectProfileColumns(columns, interview);
   });
 
   for (const [studyId, aggregate] of aggregates) {
@@ -134,6 +139,11 @@ async function buildExportResponse(
 
   const csvLines = [SUMMARY_CSV_HEADER, ...interviews.map(summaryCsvRow)];
   zip.file(SUMMARY_CSV_NAME, csvLines.join('\n'));
+  const orderedColumns = sortedProfileColumns(columns);
+  zip.file('analysis/interviews.jsonl', interviews.map(analysisJsonLine).join(''));
+  zip.file('analysis/interviews.csv', analysisInterviewsHeader(orderedColumns) + interviews.map(interview => analysisInterviewsRow(interview, orderedColumns)).join(''));
+  zip.file('analysis/profile_fields.csv', analysisCsvHeader(PROFILE_COLUMNS) + interviews.map(analysisProfileRows).join(''));
+  zip.file('analysis/README.md', analysisReadme(orderedColumns));
 
   const zipBlob = await zip.generateAsync({ type: 'blob' });
   const refusal = await beforeReturn?.();
@@ -169,7 +179,7 @@ async function streamDurableExport(store: DurableWorkspaceStorePort, studyId?: s
   // Every page carries at least one row or aggregate, which bounds the walk.
   const maximumPages = begun.count + begun.studyIds.length + MAX_EXPLORATION_ANSWERS + 1;
   const body = createInterviewExportStream({
-    pages: remainingExportPages(store, sequence, first, maximumPages, studyId),
+    pages: () => remainingExportPages(store, sequence, first, maximumPages, studyId),
     beforeFinish: async () => {
       const verified = await store.verifyExportSequence({ sequence, ...scope });
       if (verified === 'changed') throw new ExportSnapshotChangedError();
diff --git a/src/lib/export/interviewExport.ts b/src/lib/export/interviewExport.ts
index f11c092..98f6632 100644
--- a/src/lib/export/interviewExport.ts
+++ b/src/lib/export/interviewExport.ts
@@ -4,11 +4,12 @@
 // produce the same entries with the same decompressed bytes: per interview
 // NNN_<date>_<id8>.json and .md, then aggregates/<studyId>.json (with JSZip's
 // implicit aggregates/ folder entry), then summary.csv with formula-safe
-// cells. The parity tests (zipStream.test.ts, api.export.durable.test.ts)
+// cells, plus snapshot-only analysis files (analysisFiles.ts). The parity tests (zipStream.test.ts, api.export.durable.test.ts)
 // compare the two archives entry by entry.
 
 import type { StoredAggregateSynthesis, StoredInterview } from '@/types';
 import type { ExplorationAnswer } from '@/lib/exploration/types';
+import { analysisCsvHeader, analysisInterviewsHeaderParts, analysisInterviewsRow, analysisJsonLine, analysisProfileRows, analysisReadmeParts, analysisTextChunks, analysisTurnsCsv, analysisTurnsName, collectProfileColumns, PROFILE_COLUMNS, sortedProfileColumns, type ProfileColumns } from './analysisFiles';
 import { csvCell } from '@/lib/csv';
 import { analysisStatus } from '@/lib/analysisState';
 import { createZipStream, type ZipStreamLimits } from './zipStream';
@@ -25,7 +26,7 @@ export function interviewTranscriptMarkdown(interview: StoredInterview): string
     `# Interview Transcript`,
     `Study: ${interview.studyName}`,
     `Interview ID: ${interview.id}`,
-    `Date: ${new Date(interview.createdAt).toLocaleDateString()}`,
+    `Date: ${new Date(interview.createdAt).toISOString()}`,
     `Duration: ${Math.round((interview.completedAt - interview.createdAt) / 1000 / 60)} minutes`,
     ...(interviewLanguageLine(interview) ? [interviewLanguageLine(interview)!] : []),
     ``
@@ -53,7 +54,7 @@ export function interviewTranscriptMarkdown(interview: StoredInterview): string
   lines.push(``);
 
   interview.transcript.forEach(msg => {
-    const time = new Date(msg.timestamp).toLocaleTimeString();
+    const time = new Date(msg.timestamp).toISOString();
     const role = msg.role === 'user' ? 'PARTICIPANT' : 'INTERVIEWER';
     lines.push(`[${time}] ${role}:`);
     // Quoted so transcript text cannot imitate a speaker line or a heading.
@@ -142,7 +143,8 @@ export class ExportSnapshotChangedError extends Error {
 }
 
 export type InterviewExportStreamInput = {
-  pages: AsyncIterable<InterviewExportPage>;
+  /** A fresh walk of the SAME snapshot on every invocation; never begin a new export. */
+  pages: () => AsyncIterable<InterviewExportPage>;
   /**
    * Called after the last entry and before the central directory is written.
    * Throw (e.g. ExportSnapshotChangedError) to fail the archive instead.
@@ -159,23 +161,28 @@ export type InterviewExportStreamInput = {
  * sequence check, ZIP limit) errors the stream; the central directory is
  * only written after every page and `beforeFinish` succeeded, so a client
  * can never mistake a truncated download for a complete archive.
- * summary.csv is buffered as one short line per interview (the export's
- * interview ceiling bounds it); every other entry is written as it arrives.
+ * Replay the same bounded pages for combined analysis entries: no corpus-sized
+ * strings or arrays are retained. Only the profile column dictionary survives a pass.
  */
 export function createInterviewExportStream(input: InterviewExportStreamInput): ReadableStream<Uint8Array> {
   const zip = createZipStream({ modifiedAt: input.modifiedAt, limits: input.limits });
   const run = async () => {
-    const csvLines = [SUMMARY_CSV_HEADER];
+    const columns: ProfileColumns = new Map();
+    await zip.addDirectory('analysis/');
+    await zip.addDirectory('analysis/turns/');
     const seenAggregates = new Set<string>();
     const seenExplorations = new Set<string>();
     let position = 0;
-    for await (const page of input.pages) {
+    const interviewIds: string[] = [];
+    for await (const page of input.pages()) {
       for (const interview of page.interviews) {
         const baseName = interviewEntryBaseName(position, interview);
         position += 1;
+        interviewIds.push(interview.id);
         await zip.addFile(`${baseName}.json`, interviewJson(interview));
         await zip.addFile(`${baseName}.md`, interviewTranscriptMarkdown(interview));
-        csvLines.push(summaryCsvRow(interview));
+        await zip.addFile(analysisTurnsName(position - 1), analysisTurnsCsv(interview));
+        collectProfileColumns(columns, interview);
       }
       for (const aggregate of page.aggregates) {
         if (seenAggregates.size === 0) await zip.addDirectory(AGGREGATES_DIRECTORY);
@@ -191,7 +198,27 @@ export function createInterviewExportStream(input: InterviewExportStreamInput):
         await zip.addFile(entryName, explorationJson(answer));
       }
     }
-    await zip.addFile(SUMMARY_CSV_NAME, csvLines.join('\n'));
+    const orderedColumns = sortedProfileColumns(columns);
+    // Count and identity checks catch a broken replay source as well as missing pages.
+    // Durable storage itself checks the snapshot fingerprint on each page read.
+    async function* rows(header: string | Iterable<string>, row: (interview: StoredInterview) => string): AsyncGenerator<string> {
+      if (typeof header === 'string') yield header;
+      else yield* header;
+      let count = 0;
+      for await (const page of input.pages()) {
+        for (const interview of page.interviews) {
+          if (interview.id !== interviewIds[count]) throw new ExportSnapshotChangedError();
+          count += 1;
+          yield row(interview);
+        }
+      }
+      if (count !== position) throw new ExportSnapshotChangedError();
+    }
+    await zip.addFile(SUMMARY_CSV_NAME, rows(SUMMARY_CSV_HEADER, interview => `\n${summaryCsvRow(interview)}`));
+    await zip.addFile('analysis/interviews.jsonl', rows('', analysisJsonLine));
+    await zip.addFile('analysis/interviews.csv', rows(analysisTextChunks(analysisInterviewsHeaderParts(orderedColumns)), interview => analysisInterviewsRow(interview, orderedColumns)));
+    await zip.addFile('analysis/profile_fields.csv', rows(analysisCsvHeader(PROFILE_COLUMNS), analysisProfileRows));
+    await zip.addFile('analysis/README.md', analysisTextChunks(analysisReadmeParts(orderedColumns)));
     if (input.beforeFinish) await input.beforeFinish();
     await zip.finish();
   };
diff --git a/src/lib/export/zipStream.ts b/src/lib/export/zipStream.ts
index 71dc88c..cdb021d 100644
--- a/src/lib/export/zipStream.ts
+++ b/src/lib/export/zipStream.ts
@@ -1,7 +1,7 @@
 // Streaming PKZIP writer (ST-08, RT-09). Web Streams only, so the same code
 // runs in Node 24+ and workerd. Entries are deflated through
 // CompressionStream('deflate-raw') and written with data descriptors, so
-// memory is bounded by the entry being added plus the central-directory
+// memory is bounded by the entry (or current async text chunk) plus the central-directory
 // records (name + fixed fields per entry). The central directory is written
 // only by finish(); abort() or any error errors the readable side instead, so
 // a consumer never receives a well-formed archive that is missing entries.
@@ -51,7 +51,7 @@ export type ZipStreamOptions = {
 
 export type ZipStream = {
   readonly readable: ReadableStream<Uint8Array>;
-  addFile(name: string, data: string | Uint8Array): Promise<void>;
+  addFile(name: string, data: string | Uint8Array | AsyncIterable<string> | Iterable<string>): Promise<void>;
   addDirectory(name: string): Promise<void>;
   /** Writes the central directory and closes the stream. */
   finish(): Promise<void>;
@@ -200,7 +200,9 @@ export function createZipStream(options: ZipStreamOptions = {}): ZipStream {
     return bytes;
   }
 
-  async function deflateInto(data: Uint8Array): Promise<number> {
+  async function deflateInto(chunks: AsyncIterable<Uint8Array>): Promise<{ compressedSize: number; uncompressedSize: number; crc: number }> {
+    let uncompressedSize = 0;
+    let crc = 0;
     const compressor = new CompressionStream('deflate-raw');
     const input = compressor.writable.getWriter();
     const output = compressor.readable.getReader();
@@ -221,21 +223,34 @@ export function createZipStream(options: ZipStreamOptions = {}): ZipStream {
       }
     })();
     const feed = (async () => {
-      for (let start = 0; start < data.length; start += INPUT_SLICE_BYTES) {
-        await input.write(data.subarray(start, Math.min(start + INPUT_SLICE_BYTES, data.length)) as Uint8Array<ArrayBuffer>);
+      try {
+        for await (const data of chunks) {
+          uncompressedSize += data.length;
+          if (uncompressedSize > limits.maxEntryBytes) throw new ZipLimitError('entry-size');
+          crc = crc32(data, crc);
+          for (let start = 0; start < data.length; start += INPUT_SLICE_BYTES) {
+            await input.write(data.subarray(start, Math.min(start + INPUT_SLICE_BYTES, data.length)) as Uint8Array<ArrayBuffer>);
+          }
+        }
+        await input.close();
+      } catch (error) {
+        await input.abort(error).catch(() => undefined);
+        throw error;
       }
-      await input.close();
     })();
     await Promise.all([feed, pump]);
-    return compressedSize;
+    return { compressedSize, uncompressedSize, crc };
   }
 
-  async function addFile(name: string, data: string | Uint8Array): Promise<void> {
+  async function addFile(name: string, data: string | Uint8Array | AsyncIterable<string> | Iterable<string>): Promise<void> {
     begin();
     try {
       const nameBytes = encodeName(name, false);
-      const bytes = typeof data === 'string' ? encoder.encode(data) : data;
-      if (bytes.length > limits.maxEntryBytes) throw new ZipLimitError('entry-size');
+      async function* chunks(): AsyncGenerator<Uint8Array> {
+        if (typeof data === 'string') yield encoder.encode(data);
+        else if (data instanceof Uint8Array) yield data;
+        else for await (const chunk of data) yield encoder.encode(chunk);
+      }
       const entryOffset = offset;
       const flags = FLAG_DATA_DESCRIPTOR | FLAG_UTF8;
       await emit(localHeader({
@@ -246,14 +261,13 @@ export function createZipStream(options: ZipStreamOptions = {}): ZipStream {
         compressedSize: 0,
         uncompressedSize: 0,
       }));
-      const crc = crc32(bytes);
-      const compressedSize = await deflateInto(bytes);
+      const { crc, compressedSize, uncompressedSize } = await deflateInto(chunks());
       const descriptor = new Uint8Array(DATA_DESCRIPTOR_BYTES);
       const view = new DataView(descriptor.buffer);
       view.setUint32(0, DATA_DESCRIPTOR_SIGNATURE, true);
       view.setUint32(4, crc, true);
       view.setUint32(8, compressedSize, true);
-      view.setUint32(12, bytes.length, true);
+      view.setUint32(12, uncompressedSize, true);
       await emit(descriptor);
       central.push({
         name: nameBytes,
@@ -261,7 +275,7 @@ export function createZipStream(options: ZipStreamOptions = {}): ZipStream {
         method: METHOD_DEFLATE,
         crc,
         compressedSize,
-        uncompressedSize: bytes.length,
+        uncompressedSize,
         offset: entryOffset,
         externalAttributes: 0,
       });
diff --git a/tests/unit/api.export.durable.test.ts b/tests/unit/api.export.durable.test.ts
index 9638358..1f13072 100644
--- a/tests/unit/api.export.durable.test.ts
+++ b/tests/unit/api.export.durable.test.ts
@@ -11,7 +11,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import JSZip from 'jszip';
 import type { StoredAggregateSynthesis, StoredInterview } from '@/types';
-import { makeStoredInterview } from '../fixtures/models';
+import { makeStoredInterview, makeStudyConfig } from '../fixtures/models';
 import { standaloneTestContext } from '../helpers/workspaceStoreFixture';
 import type { RedisPort } from '@/lib/redisPort';
 
@@ -112,6 +112,13 @@ function fixtures(): { interviews: StoredInterview[]; aggregates: StoredAggregat
       id: 'session-cc33-newest',
       studyId: 'study-b',
       studyName: '+HYPERLINK("x") Ünïcödé study',
+      studyRevision: 3,
+      collectionConfig: makeStudyConfig({ interviewLanguages: ['zh', 'en'], voiceInput: 'browser' }),
+      interviewLanguage: 'zh', providerCommitment: 'fixed',
+      conductedByProvider: 'openai', conductedByModel: 'fixture-conversation',
+      consentHash: 'a'.repeat(64), consentAcceptedAt: base,
+      consentTransport: 'cloudflare-gateway', aiTransport: 'cloudflare-gateway',
+      aiProvider: 'gemini', aiModel: 'fixture-analysis',
       createdAt: base + 3_000_000,
       completedAt: base + 3_900_000,
       participantProfile: {
@@ -124,6 +131,7 @@ function fixtures(): { interviews: StoredInterview[]; aggregates: StoredAggregat
         timestamp: base,
       },
       transcript: [
+        { id: 'system', role: 'system', content: 'Synthetic system message', timestamp: base },
         { id: 'm-1', role: 'ai', content: 'Hello 👋', timestamp: base + 3_000_000 },
         { id: 'm-2', role: 'user', content: '=cmd|calc', timestamp: base + 3_060_000 },
       ],
@@ -326,12 +334,21 @@ describe('GET /api/interviews/export on Cloudflare (RT-09, ST-08, F1)', () => {
     expect(entries.map((entry) => entry.name)).toEqual(reference.map((entry) => entry.name));
     expect(entries).toEqual(reference);
     expect(entries.map((entry) => entry.name)).toEqual([
-      '001_2026-09-20_session-.json', '001_2026-09-20_session-.md',
-      '002_2026-09-20_session-.json', '002_2026-09-20_session-.md',
-      '003_2026-09-20_session-.json', '003_2026-09-20_session-.md',
-      '004_2026-09-20_session-.json', '004_2026-09-20_session-.md',
+      'analysis/', 'analysis/turns/',
+      '001_2026-09-20_session-.json', '001_2026-09-20_session-.md', 'analysis/turns/001.csv',
+      '002_2026-09-20_session-.json', '002_2026-09-20_session-.md', 'analysis/turns/002.csv',
+      '003_2026-09-20_session-.json', '003_2026-09-20_session-.md', 'analysis/turns/003.csv',
+      '004_2026-09-20_session-.json', '004_2026-09-20_session-.md', 'analysis/turns/004.csv',
       'aggregates/', 'aggregates/study-b.json', 'aggregates/study-a.json', 'summary.csv',
+      'analysis/interviews.jsonl', 'analysis/interviews.csv', 'analysis/profile_fields.csv', 'analysis/README.md',
     ]);
+    const jsonl = entries.find(entry => entry.name === 'analysis/interviews.jsonl')!.text!;
+    const records = jsonl.trimEnd().split('\n').map(line => JSON.parse(line));
+    expect(records).toHaveLength(data.interviews.length);
+    expect(records[0].turns.map((turn: { index: number }) => turn.index)).toEqual([2, 3]);
+    expect(records[0].interview).toMatchObject({ language: 'zh', languageTag: 'zh-Hans', voiceInput: 'browser' });
+    expect(records[0].consent.conductedBy.model).toBe('fixture-conversation');
+    expect(records[0].analysis.model).toBe('fixture-analysis');
     const csv = entries.find((entry) => entry.name === 'summary.csv')!.text!;
     expect(csv).toContain(`"'+HYPERLINK(""x"") Ünïcödé study"`);
     expect(csv).toContain(`"'@bottom line"`);
@@ -341,7 +358,7 @@ describe('GET /api/interviews/export on Cloudflare (RT-09, ST-08, F1)', () => {
     expect(methods().filter((method) => method === 'beginExport')).toHaveLength(1);
     expect(rpcCalls[0].input).toEqual({ maximum: 500 });
     const pages = rpcCalls.filter((call) => call.method === 'readExportPage');
-    expect(pages).toHaveLength(data.interviews.length + data.aggregates.length);
+    expect(pages).toHaveLength(1 + 5 * (data.interviews.length + data.aggregates.length - 1));
     for (const page of pages) {
       expect(page.input.sequence).toBe(SEQUENCE);
       expect(page.input.pageSize).toBeLessThanOrEqual(200);
@@ -366,6 +383,20 @@ describe('GET /api/interviews/export on Cloudflare (RT-09, ST-08, F1)', () => {
     expect(methods()).toEqual(['beginExport']);
   });
 
+  it('refuses a partial archive when an analysis-file replay cannot reproduce the snapshot', async () => {
+    let reads = 0;
+    const data = fixtures();
+    scriptExport(data, { pageHook: () => {
+      reads += 1;
+      // Initial six pages, then summary pass, then fail inside JSONL's pass.
+      return reads === 12 ? { status: 'changed' } : null;
+    } });
+    const { bytes, error } = await collect(await GET());
+    expect(error).toBeInstanceOf(Error);
+    expect(await isCompleteZipArchive(new Blob([bytes as Uint8Array<ArrayBuffer>]))).toBe(false);
+    expect(methods()).not.toContain('verifyExportSequence');
+  });
+
   it('F1/ST-08: a snapshot change before the response starts is 409 EXPORT_CHANGED, retryable', async () => {
     scriptExport(fixtures(), { pageHook: (cursor) => (cursor === null ? { status: 'changed' } : null) });
 
diff --git a/tests/unit/api.export.scoped.test.ts b/tests/unit/api.export.scoped.test.ts
index 7374b06..f892a35 100644
--- a/tests/unit/api.export.scoped.test.ts
+++ b/tests/unit/api.export.scoped.test.ts
@@ -2,7 +2,7 @@
 
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import JSZip from 'jszip';
-import { makeStoredInterview, makeStoredStudy } from '../fixtures/models';
+import { makeStoredInterview, makeStoredStudy, makeStudyConfig } from '../fixtures/models';
 import type { ExplorationAnswer } from '@/lib/exploration/types';
 import type { DurableWorkspaceStorePort, WorkspaceStorePort } from '@/lib/storage/types';
 import { createInterviewExportStream } from '@/lib/export/interviewExport';
@@ -43,6 +43,32 @@ beforeEach(() => {
 });
 
 describe('study-scoped export', () => {
+  it('has byte-identical analysis entries through the actual scoped Node and durable routes', async () => {
+    const interviews = [makeStoredInterview({ id: 'interview-a', studyId: 'study-a', studyRevision: 1,
+      collectionConfig: makeStudyConfig({ interviewLanguages: ['fr', 'zh'] }), interviewLanguage: 'fr' })];
+    listInterviews.mockResolvedValue({ status: 'ok', items: interviews });
+    const node = await GET(request());
+    const nodeZip = await JSZip.loadAsync(await node.arrayBuffer(), { checkCRC32: true });
+    const beginExport = vi.fn().mockResolvedValue({ status: 'ok', sequence: 3, count: 1, studyIds: ['study-a'] });
+    const readExportPage = vi.fn().mockImplementation(async ({ cursor }) => cursor === null
+      ? { status: 'ok', interviews, aggregates: [], nextCursor: 'notebook' }
+      : { status: 'ok', interviews: [], aggregates: [], explorations: [answer()], nextCursor: null });
+    const verifyExportSequence = vi.fn().mockResolvedValue('unchanged');
+    access.getAuthorizedResearcherStudyContext.mockResolvedValue({ authorized: true, context: { store: {
+      ...store, backend: 'durable-object', beginExport, readExportPage, verifyExportSequence,
+    } } });
+    const durable = await GET(request());
+    const durableZip = await JSZip.loadAsync(await durable.arrayBuffer(), { checkCRC32: true });
+    const analysisNames = Object.keys(nodeZip.files).filter(name => name.startsWith('analysis/'));
+    expect(Object.keys(durableZip.files).filter(name => name.startsWith('analysis/'))).toEqual(analysisNames);
+    for (const name of analysisNames) {
+      expect(await durableZip.files[name].async('uint8array'), name).toEqual(await nodeZip.files[name].async('uint8array'));
+    }
+    const records = (await durableZip.file('analysis/interviews.jsonl')!.async('string')).trim().split('\n').map(line => JSON.parse(line));
+    expect(records.map(record => record.study.id)).toEqual(['study-a']);
+    expect(verifyExportSequence).toHaveBeenCalledWith({ sequence: 3, studyId: 'study-a' });
+  });
+
   it('walks all notebook pages instead of silently exporting only the first 25 answers', async () => {
     listAnswers.mockResolvedValueOnce({ status: 'ok', answers: [answer()], nextCursor: '1:answer-a' })
       .mockResolvedValueOnce({ status: 'ok', answers: [{ ...answer(), id: 'answer-b' }], nextCursor: null });
@@ -124,7 +150,7 @@ describe('study-scoped export', () => {
     const beginExport = vi.fn().mockResolvedValue({ status: 'ok', sequence: 3, count: 0, studyIds: ['study-a'] });
     const readExportPage = vi.fn()
       .mockResolvedValueOnce({ status: 'ok', interviews: [], aggregates: [], explorations: [answer()], nextCursor: 'next' })
-      .mockResolvedValueOnce({ status: 'ok', interviews: [], aggregates: [], explorations: [], nextCursor: null });
+      .mockResolvedValue({ status: 'ok', interviews: [], aggregates: [], explorations: [], nextCursor: null });
     const verifyExportSequence = vi.fn().mockResolvedValue('unchanged');
     const durable = { ...store, backend: 'durable-object', beginExport, readExportPage, verifyExportSequence } as unknown as DurableWorkspaceStorePort;
     access.getAuthorizedResearcherStudyContext.mockResolvedValue({ authorized: true, context: { store: durable } });
@@ -133,7 +159,7 @@ describe('study-scoped export', () => {
     const archive = await response.blob();
     expect(await isCompleteZipArchive(archive)).toBe(true);
     expect(beginExport).toHaveBeenCalledWith({ maximum: 500, studyId: 'study-a' });
-    expect(readExportPage).toHaveBeenCalledTimes(2);
+    expect(readExportPage).toHaveBeenCalledTimes(6);
     for (const [input] of readExportPage.mock.calls) expect(input.studyId).toBe('study-a');
     expect(verifyExportSequence).toHaveBeenCalledWith({ sequence: 3, studyId: 'study-a' });
   });
@@ -142,7 +168,7 @@ describe('study-scoped export', () => {
     const node = await GET(request());
     const nodeZip = await JSZip.loadAsync(await node.arrayBuffer());
     const interview = makeStoredInterview({ id: 'interview-a', studyId: 'study-a' });
-    const streamed = createInterviewExportStream({ pages: (async function* () { yield { interviews: [interview], aggregates: [], explorations: [answer()] }; })() });
+    const streamed = createInterviewExportStream({ pages: async function* () { yield { interviews: [interview], aggregates: [], explorations: [answer()] }; } });
     const zip = await JSZip.loadAsync(await new Response(streamed).arrayBuffer());
     expect(await zip.file('explorations/study-a/answer-a.json')!.async('string')).toBe(await nodeZip.file('explorations/study-a/answer-a.json')!.async('string'));
   });
diff --git a/tests/unit/zipStream.test.ts b/tests/unit/zipStream.test.ts
index 2ac61d0..b821ae7 100644
--- a/tests/unit/zipStream.test.ts
+++ b/tests/unit/zipStream.test.ts
@@ -131,6 +131,35 @@ describe('createZipStream (RT-09, ST-08)', () => {
     expect(loaded.files['plain.txt'].date.toISOString()).toBe('2026-09-23T12:34:56.000Z');
   });
 
+  it('streams one entry from chunks with correct cumulative CRC and lengths', async () => {
+    const zip = createZipStream();
+    const out = collect(zip.readable);
+    async function* chunks() { yield '研究\n'; yield '"quoted"'; yield ''; yield 'final\n'; }
+    await zip.addFile('analysis.jsonl', chunks());
+    await zip.finish();
+    const { bytes, error } = await out;
+    expect(error).toBeNull();
+    const loaded = await JSZip.loadAsync(bytes, { checkCRC32: true });
+    expect(await loaded.file('analysis.jsonl')!.async('string')).toBe('研究\n"quoted"final\n');
+  });
+
+  it('counts cumulative chunk bytes and abandons a file on a source failure without closing records', async () => {
+    for (const failSource of [true, false]) {
+      const zip = createZipStream({ limits: { maxEntryBytes: 10 } });
+      const out = collect(zip.readable);
+      async function* chunks() {
+        yield '123456';
+        if (failSource) throw new ExportSnapshotChangedError();
+        yield '78901';
+      }
+      await expect(zip.addFile('analysis.jsonl', chunks())).rejects.toThrow();
+      await expect(zip.finish()).rejects.toThrow();
+      const { bytes, error } = await out;
+      expect(error).toBeInstanceOf(failSource ? ExportSnapshotChangedError : ZipLimitError);
+      expect(containsSignature(bytes, EOCD)).toBe(false);
+    }
+  });
+
   it('computes the standard CRC-32', () => {
     expect(crc32(new TextEncoder().encode('123456789'))).toBe(0xcbf43926);
     expect(crc32(new Uint8Array())).toBe(0);
@@ -302,7 +331,7 @@ describe('createInterviewExportStream parity with the Node JSZip export (ST-08,
     // Paged exactly as the Durable Object pages: interviews, then aggregates
     // in first-seen study order.
     const stream = createInterviewExportStream({
-      pages: pagesOf([
+      pages: () => pagesOf([
         { interviews: interviews.slice(0, 2), aggregates: [] },
         { interviews: interviews.slice(2), aggregates: [] },
         { interviews: [], aggregates: [aggregates.get('study-b')!] },
@@ -325,7 +354,7 @@ describe('createInterviewExportStream parity with the Node JSZip export (ST-08,
   it('ST-08: an export without aggregates matches JSZip too (no aggregates/ folder)', async () => {
     const { interviews } = fixtures();
     const reference = await jszipReference(interviews, new Map());
-    const { bytes } = await collect(createInterviewExportStream({ pages: pagesOf([{ interviews, aggregates: [] }]) }));
+    const { bytes } = await collect(createInterviewExportStream({ pages: () => pagesOf([{ interviews, aggregates: [] }]) }));
     expect(await entriesOf(bytes)).toEqual(reference);
   });
 
@@ -336,7 +365,7 @@ describe('createInterviewExportStream parity with the Node JSZip export (ST-08,
       yield { interviews: interviews.slice(0, 1), aggregates: [] };
       throw new ExportSnapshotChangedError();
     }
-    const { bytes, error } = await collect(createInterviewExportStream({ pages: changing(), onError }));
+    const { bytes, error } = await collect(createInterviewExportStream({ pages: changing, onError }));
     expect(error).toBeInstanceOf(ExportSnapshotChangedError);
     expect(onError).toHaveBeenCalledWith(expect.any(ExportSnapshotChangedError));
     expect(containsSignature(bytes, EOCD)).toBe(false);
@@ -353,7 +382,7 @@ describe('createInterviewExportStream parity with the Node JSZip export (ST-08,
       throw new Error('observer failed');
     });
     const outcome = await Promise.race([
-      collect(createInterviewExportStream({ pages: changing(), onError })),
+      collect(createInterviewExportStream({ pages: changing, onError })),
       new Promise<'pending'>((resolve) => setTimeout(() => resolve('pending'), 2_000)),
     ]);
     expect(outcome).not.toBe('pending');
@@ -366,7 +395,7 @@ describe('createInterviewExportStream parity with the Node JSZip export (ST-08,
   it('ST-08: a failed final sequence check omits archive finalization', async () => {
     const { interviews } = fixtures();
     const { bytes, error } = await collect(createInterviewExportStream({
-      pages: pagesOf([{ interviews, aggregates: [] }]),
+      pages: () => pagesOf([{ interviews, aggregates: [] }]),
       beforeFinish: async () => {
         throw new ExportSnapshotChangedError();
       },
diff --git a/tests/workers/exports.test.ts b/tests/workers/exports.test.ts
index 5f0413f..d1750ac 100644
--- a/tests/workers/exports.test.ts
+++ b/tests/workers/exports.test.ts
@@ -224,7 +224,7 @@ describe('researcher export paging (ST-08, RT-09)', () => {
       for (const page of pages) yield { interviews: page.interviews, aggregates: page.aggregates };
     }
     const archive = new Uint8Array(await new Response(createInterviewExportStream({
-      pages: source(),
+      pages: source,
       beforeFinish: async () => {
         const verified = await stub.verifyExportSequence({ sequence: begun.sequence });
         if (verified.status !== 'unchanged') throw new ExportSnapshotChangedError();
@@ -232,13 +232,20 @@ describe('researcher export paging (ST-08, RT-09)', () => {
     })).arrayBuffer());
     const zip = await JSZip.loadAsync(archive, { checkCRC32: true });
     expect(Object.keys(zip.files)).toEqual([
-      '001_2026-09-20_iv-b2.json', '001_2026-09-20_iv-b2.md',
-      '002_2026-09-20_iv-a2.json', '002_2026-09-20_iv-a2.md',
-      '003_2026-09-20_iv-b1.json', '003_2026-09-20_iv-b1.md',
-      '004_2026-09-20_iv-a1.json', '004_2026-09-20_iv-a1.md',
+      'analysis/', 'analysis/turns/',
+      '001_2026-09-20_iv-b2.json', '001_2026-09-20_iv-b2.md', 'analysis/turns/001.csv',
+      '002_2026-09-20_iv-a2.json', '002_2026-09-20_iv-a2.md', 'analysis/turns/002.csv',
+      '003_2026-09-20_iv-b1.json', '003_2026-09-20_iv-b1.md', 'analysis/turns/003.csv',
+      '004_2026-09-20_iv-a1.json', '004_2026-09-20_iv-a1.md', 'analysis/turns/004.csv',
       'aggregates/', 'aggregates/study-b.json', 'aggregates/study-a.json', 'summary.csv',
+      'analysis/interviews.jsonl', 'analysis/interviews.csv', 'analysis/profile_fields.csv', 'analysis/README.md',
     ]);
     expect(JSON.parse(await zip.file('004_2026-09-20_iv-a1.json')!.async('string'))).toEqual(complete);
+    const analysis = (await zip.file('analysis/interviews.jsonl')!.async('string')).trimEnd().split('\n').map(line => JSON.parse(line));
+    expect(analysis.map(interview => interview.interview.id)).toEqual(['iv-b2', 'iv-a2', 'iv-b1', 'iv-a1']);
+    expect(analysis[3].analysis.model).toBe('gpt-fixture-2026');
+    expect((await zip.file('analysis/interviews.csv')!.async('uint8array')).slice(0, 3)).toEqual(new Uint8Array([239, 187, 191]));
+    expect(await zip.file('analysis/README.md')!.async('string')).toContain('Before sharing this file with an AI tool');
     const csv = await zip.file('summary.csv')!.async('string');
     expect(csv.split('\n')).toHaveLength(5);
     expect(csv).toContain('"complete"');
@@ -385,6 +392,7 @@ describe('researcher export paging (ST-08, RT-09)', () => {
       const begun = await stub.beginExport({ maximum: 500 });
       if (begun.status !== 'ok') throw new Error(begun.status);
       const { sequence } = begun;
+      let mutated = false;
       async function* pages(): AsyncGenerator<InterviewExportPage> {
         let cursor: string | null = null;
         for (;;) {
@@ -392,13 +400,16 @@ describe('researcher export paging (ST-08, RT-09)', () => {
           if (page.status === 'changed') throw new ExportSnapshotChangedError();
           if (page.status !== 'ok') throw new Error(page.status);
           yield { interviews: page.interviews, aggregates: page.aggregates };
-          if (cursor === null) await duringFirstPage();
+          if (cursor === null && !mutated) {
+            mutated = true;
+            await duringFirstPage();
+          }
           cursor = page.nextCursor;
           if (cursor === null) return;
         }
       }
       const reader = createInterviewExportStream({
-        pages: pages(),
+        pages,
         beforeFinish: async () => {
           const verified = await stub.verifyExportSequence({ sequence });
           if (verified.status !== 'unchanged') throw new ExportSnapshotChangedError();

From 3aff321febb4200b67e3fd220b0277bf96e90e90 Mon Sep 17 00:00:00 2001
From: Xule Lin <43122877+linxule@users.noreply.github.com>
Date: Sat, 10 Oct 2026 14:31:07 +0200
Subject: [PATCH 3/5] docs(export): document the analysis files

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 AGENTS.md                      |  1 +
 README.md                      | 14 +++++++++++++-
 docs/releases/v5.4.0.md        | 16 ++++++++++++++++
 src/components/Dashboard.tsx   |  1 +
 src/components/StudyDetail.tsx |  2 +-
 5 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 60f6f78..cb664ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,7 @@ The sample-workspace seed is not the public demo. `/demo` is component-memory-on
 
 - Standalone projects and membership contracts/validation: `src/lib/projects/`; project HTTP routes: `src/app/api/projects/`, `src/app/api/studies/[id]/project/`
 - Project storage: `src/lib/storage/redisProjects.ts`, `cloudflare/workspace/projects.ts`, with the project sub-port in `src/lib/storage/types.ts` and RPC validation in `src/lib/storage/durableObject.ts`
+- Study ZIP analysis views: `src/lib/export/analysisFiles.ts`; both ZIP paths use these snapshot-only builders. Combined entries stream from repeated reads of the same fenced snapshot; turn CSVs are per-interview shards. Keep citation indices 1-based over the full stored transcript, including omitted system-message positions.
 - Shared per-study transcript sources and bounded project composition: `src/lib/export/studyTranscriptsSource.ts`, `src/lib/export/projectTranscriptsMarkdown.ts`; typed browser client: `src/services/projectService.ts`
 - Researcher studies/interviews and atomic Redis scripts: `src/lib/kv.ts`
 - Field-level JSON patching inside Redis Lua (preserves untouched value types): `src/lib/studyJsonLua.ts`
diff --git a/README.md b/README.md
index 302f293..7919af9 100644
--- a/README.md
+++ b/README.md
@@ -331,7 +331,19 @@ For researchers:
 6. Choose a dataset, run aggregate analysis, or ask questions in **Explore**; export the study or workspace.
 7. Pause and resume collection without replacing links, or delete a study in Settings when its retention period ends.
 
-**Export this study** downloads a ZIP of raw records, transcripts, the aggregate and the notebook. **Export transcripts (.md)** downloads one Markdown file with every saved transcript of the study, for reading or for another analysis tool. Transcript text is quoted exactly as saved, and each interview lists what its participant was told about the AI. If a participant was promised that the study uses only one provider and model, sending the file to a different AI service may break that promise. A download that did not finish is refused rather than saved.
+**Export this study** downloads a ZIP of raw records, transcripts, the aggregate and the notebook, plus an `analysis/` folder for coding tools and spreadsheets. The same analysis files are included in workspace ZIP exports.
+
+The ZIP retains the per-interview `NNN_*.json` and `.md`, `summary.csv`, `aggregates/` and `explorations/`. It adds:
+
+- `analysis/README.md`: field definitions, historical-label rules and the consent/provider sharing warning.
+- `analysis/interviews.jsonl`: one interview per line, with collection context, recorded consent and analysis provenance, profile values and verbatim turns.
+- `analysis/interviews.csv`: interview-level data and one column per observed profile field ID, labeled from the newest interview.
+- `analysis/turns/NNN.csv`: one turn table per interview to bound export memory; indices match analysis citations, including gaps for omitted system messages.
+- `analysis/profile_fields.csv`: profile values in long form with their labels at collection.
+
+CSVs use UTF-8 with BOM and CRLF. Formula-like text is protected with an added apostrophe; use JSONL for verbatim quotes. Unknown historical fields are not filled from today’s study configuration. ZIP Markdown dates are ISO UTC.
+
+**Export transcripts (.md)** downloads one Markdown file with every saved transcript of the study, for reading or for another analysis tool. Transcript text is quoted exactly as saved, and each interview lists what its participant was told about the AI. If a participant was promised that the study uses only one provider and model, sending the file to a different AI service may break that promise. A download that did not finish is refused rather than saved.
 
 ### Explore this study
 
diff --git a/docs/releases/v5.4.0.md b/docs/releases/v5.4.0.md
index 427781f..bb7df11 100644
--- a/docs/releases/v5.4.0.md
+++ b/docs/releases/v5.4.0.md
@@ -75,3 +75,19 @@ browser locality or language-pack support.
 - Run the workers/Redis shared revision contract and browser lanes listed in
   `CHANGES-device-voice.md`. No deployment or real browser verification was done
   in the restricted implementation sandbox.
+
+## Richer export
+
+Study and workspace ZIP downloads now include an `analysis/` folder for AI coding tools and spreadsheets. No new export button or third-party adapter is required.
+
+- `README.md` defines every field and repeats the Markdown export’s consent/provider sharing warning.
+- `interviews.jsonl` holds one interview per line with its saved collection protocol, consent and provider records, synthesis, profile and verbatim turns.
+- `interviews.csv` offers an interview-level table, including dynamic profile columns labeled from the newest interview.
+- `turns/NNN.csv` provides a turn table per interview, keeping export memory bounded. Turn indices match analysis citations: skipped system messages leave gaps.
+- `profile_fields.csv` preserves each profile value’s historical label and extraction status.
+
+CSV files use UTF-8 with BOM and CRLF. Formula-like text receives a protective apostrophe; JSONL is the source for verbatim quotations. Missing historical configuration remains missing, never reconstructed from the current study. Per-interview Markdown timestamps in the ZIP now use ISO UTC.
+
+Node and Cloudflare produce the same file contents. Cloudflare reads the same captured snapshot in bounded passes, and the archive is finalized only after all files and the final sequence check succeed. Existing raw JSON, Markdown, summary CSV, aggregate and notebook exports remain included.
+
+Before sharing these files with another AI service, check each participant’s recorded provider commitment. Exporting data does not change that promise.
diff --git a/src/components/Dashboard.tsx b/src/components/Dashboard.tsx
index 1c29183..ffdfcb2 100644
--- a/src/components/Dashboard.tsx
+++ b/src/components/Dashboard.tsx
@@ -213,6 +213,7 @@ export default function Dashboard() {
           <Button
             type="button"
             variant="primary"
+            title="ZIP with raw records, transcripts, saved analyses, and analysis JSONL/CSV files with a data dictionary"
             onClick={() => void handleExportAll()}
             disabled={exporting || blockedByOperation}
           >
diff --git a/src/components/StudyDetail.tsx b/src/components/StudyDetail.tsx
index 70b07ff..3c25592 100644
--- a/src/components/StudyDetail.tsx
+++ b/src/components/StudyDetail.tsx
@@ -1133,7 +1133,7 @@ const StudyDetail: React.FC<StudyDetailProps> = ({ studyId }) => {
             <p className="mt-2 max-w-measure text-[13px] text-ink-700">A collection-configuration edit advances the revision and invalidates earlier participant authority. Retained interviews remain available; choose their revisions explicitly for analysis. Pausing access does not change the protocol revision.</p>
             <div className="mt-3 flex flex-wrap gap-3">
               <Button variant="primary" disabled={operationPending} onClick={() => router.push(`/setup?prefill=edit&studyId=${encodeURIComponent(studyId)}`)}>Edit study</Button>
-              <Button variant="quiet" disabled={operationPending || isExporting} onClick={() => void handleExportStudy()}>{isExporting ? 'Preparing study export…' : 'Export this study'}</Button>
+              <Button variant="quiet" disabled={operationPending || isExporting} onClick={() => void handleExportStudy()} title="ZIP with raw records, transcripts, saved analyses, and analysis JSONL/CSV files with a data dictionary">{isExporting ? 'Preparing study export…' : 'Export this study'}</Button>
               <Button variant="quiet" disabled={operationPending || isExportingTranscripts || study.interviewCount === 0} onClick={() => void handleExportTranscripts()} title="All transcripts in one Markdown file, with what each participant was told about the AI">{isExportingTranscripts ? 'Preparing transcripts…' : 'Export transcripts (.md)'}</Button>
             </div>
           </section>

From 749e2e1acecbb39157d0e1e4c5be253cb26f6a26 Mon Sep 17 00:00:00 2001
From: Xule Lin <43122877+linxule@users.noreply.github.com>
Date: Sat, 10 Oct 2026 14:43:41 +0200
Subject: [PATCH 4/5] fix(export): write numbers as numbers in the analysis
 CSVs

The formula guard prefixed an apostrophe to negative numbers (offset_s can be
negative), so spreadsheets read them as text. A finite number cannot carry a
formula; text cells are still guarded. From the Kimi review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/lib/export/analysisFiles.ts  | 8 ++++++--
 tests/unit/analysisFiles.test.ts | 1 +
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/lib/export/analysisFiles.ts b/src/lib/export/analysisFiles.ts
index e3d8647..f5d38fd 100644
--- a/src/lib/export/analysisFiles.ts
+++ b/src/lib/export/analysisFiles.ts
@@ -73,7 +73,11 @@ export function analysisJsonLine(interview: StoredInterview): string {
 
 /** CSV record separators AND embedded text newlines are CRLF; JSONL retains exact text. */
 export function analysisCsvRow(cells: readonly unknown[]): string {
-  return cells.map(cell => csvCell(cell === undefined || cell === null ? '' : String(cell).replace(/\r\n?|\n/g, '\r\n'))).join(',') + '\r\n';
+  return cells.map(cell => {
+    // A finite number cannot carry a formula; guarding it would turn -0.5 into text.
+    if (typeof cell === 'number' && Number.isFinite(cell)) return `"${String(cell)}"`;
+    return csvCell(cell === undefined || cell === null ? '' : String(cell).replace(/\r\n?|\n/g, '\r\n'));
+  }).join(',') + '\r\n';
 }
 export const analysisCsvHeader = (cells: readonly string[]) => '\uFEFF' + analysisCsvRow(cells);
 
@@ -191,7 +195,7 @@ These views use each interview's own saved collectionConfig and consent/provider
 - profile_fields.csv: one row per saved profile field value, preserving the label at collection.
 - README.md: this data dictionary and sharing guidance.
 
-All CSVs are UTF-8 with BOM, CRLF record endings and quoted cells. Embedded text newlines are normalized to CRLF. Every cell, including headers, passes the spreadsheet formula-injection guard. CSV text cells may start with an added apostrophe (') for that guard: use the JSONL for verbatim quotes, not CSV.
+All CSVs are UTF-8 with BOM, CRLF record endings and quoted cells. Embedded text newlines are normalized to CRLF. Every text cell, including headers, passes the spreadsheet formula-injection guard; numbers are written as plain numbers. CSV text cells may start with an added apostrophe (') for that guard: use the JSONL for verbatim quotes, not CSV.
 
 ## interviews.csv columns and JSONL fields
 
diff --git a/tests/unit/analysisFiles.test.ts b/tests/unit/analysisFiles.test.ts
index 1bae88a..133c4e8 100644
--- a/tests/unit/analysisFiles.test.ts
+++ b/tests/unit/analysisFiles.test.ts
@@ -99,6 +99,7 @@ describe('analysis file builders', () => {
     const parsed = parseCsv(csv);
     expect(parsed[0]).toEqual(parsed[1]);
     expect(parsed[0]).toEqual(["'=calc", "' +calc", "'-1", "'@fn", "'\tfoo", "'\r\nbar", '研究,"引文"']);
+    expect(analysisCsvRow([-0.5, 12, '-0.5'])).toBe(`"-0.5","12","'-0.5"\r\n`);
     const turns = analysisTurnsCsv(fixture());
     expect(parseCsv(turns)[2][9]).toBe("'=研究, \"引文\"\r\n第二行\r\n第三行\r\n尾行");
   });

From 18a94eda61500db76fa0fdd99f0ab8b6e17360d8 Mon Sep 17 00:00:00 2001
From: Xule Lin <43122877+linxule@users.noreply.github.com>
Date: Sat, 10 Oct 2026 15:04:42 +0200
Subject: [PATCH 5/5] test(artifact): count interview Markdown separately from
 the analysis files

The ST-08 journey counted every .md in the archive; analysis/README.md is now
one more. Assert the analysis entries exist instead, with one turn shard and
one JSONL line per interview, through the built Worker.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 tests/cloudflare-artifact/journeys.artifact.test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tests/cloudflare-artifact/journeys.artifact.test.ts b/tests/cloudflare-artifact/journeys.artifact.test.ts
index 5e0a96d..b2e17eb 100644
--- a/tests/cloudflare-artifact/journeys.artifact.test.ts
+++ b/tests/cloudflare-artifact/journeys.artifact.test.ts
@@ -704,7 +704,10 @@ describe('operator status and an abandoned export on one workspace (OPS-01, ST-0
 
     const { zip, bytes } = await exportZip(app, researcher);
     expect(interviewEntries(zip)).toHaveLength(3);
-    expect(Object.keys(zip.files).filter((name) => name.endsWith('.md'))).toHaveLength(3);
+    expect(Object.keys(zip.files).filter((name) => name.endsWith('.md') && !name.startsWith('analysis/'))).toHaveLength(3);
+    for (const name of ['analysis/README.md', 'analysis/interviews.jsonl', 'analysis/interviews.csv', 'analysis/profile_fields.csv']) expect(zip.file(name), name).toBeTruthy();
+    expect(Object.keys(zip.files).filter((name) => /^analysis\/turns\/\d{3}\.csv$/.test(name))).toHaveLength(3);
+    expect((await zip.file('analysis/interviews.jsonl')!.async('string')).trim().split('\n')).toHaveLength(3);
     const summary = (await zip.file('summary.csv')!.async('string')).split('\n').filter(Boolean);
     expect(summary).toHaveLength(4);
     for (const interviewId of interviewIds) expect(summary.some((row) => row.includes(`"${interviewId}"`))).toBe(true);