argus-decision-mcp 1.0.0

package/dist/lib/receipt.js

@@ -0,0 +1,83 @@
+import fs from 'fs';
+import { deBom } from './deBom.js';
+import { atomicWriteJson } from './atomic-write.js';
+import { receiptPath } from './layout.js';
+import { SCHEMA_VERSION, SPINE_INVARIANTS } from './spine.js';
+/**
+ * The Judgment Receipt (blueprint §2.3 + addendum C/E/N7). The differentiated
+ * asset: a falsifiable prediction sealed, brought back, and checked against
+ * reality, with AI-verdict literally null.
+ *
+ * The seal-time fields (real_question / unverified_assumption / human_only /
+ * human_judgment) are captured at SEAL — without them the receipt's
+ * "...made by Me. (not the model)" line is blank, which is the whole point.
+ */
+/** Sentinel for a judgment field the user chose not to name (addendum: explicit
+ * skip trace, not a silent blank and not a forced gate). */
+export const SKIPPED = '(skipped)';
+/** Write the seal-time receipt. Single write (no read-merge race, E).
+ *  Judgment fields left unnamed are recorded as an explicit skip, not a silent
+ *  blank — the spine keeps the escape (you can still seal) but the omission is
+ *  honest and visible. */
+export async function writeSealReceipt(argusDir, seed, now) {
+    const skipped = [];
+    const field = (name, value) => {
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value;
+        skipped.push(name);
+        return SKIPPED;
+    };
+    const receipt = {
+        v: SCHEMA_VERSION,
+        id: seed.id,
+        created_at: now,
+        real_question: field('real_question', seed.real_question),
+        unverified_assumption: field('unverified_assumption', seed.unverified_assumption),
+        human_only: field('human_only', seed.human_only),
+        human_judgment: field('human_judgment', seed.human_judgment),
+        human_judgment_owner: 'user',
+        skipped,
+        predicate: seed.predicate,
+        check_by: seed.check_by,
+        ...(seed.basis ? { basis: seed.basis } : {}),
+        ai_verdict: SPINE_INVARIANTS.aiVerdict,
+    };
+    await atomicWriteJson(receiptPath(argusDir, seed.id), receipt);
+    return receipt;
+}
+/** Patch the receipt at settle time. Reads the seal-time receipt, adds the reality fields, single atomic write. */
+export async function writeSettleReceipt(argusDir, id, patch, 
+/** Ledger-replay fallback when the seal-time receipt file was lost (11 S7):
+ *  without it the rebuilt receipt printed empty quotes for the prediction. */
+fallback) {
+    const existing = readReceipt(argusDir, id);
+    const base = existing ?? {
+        v: SCHEMA_VERSION, id, created_at: patch.settled_at,
+        real_question: SKIPPED, unverified_assumption: SKIPPED, human_only: SKIPPED, human_judgment: SKIPPED,
+        human_judgment_owner: 'user', skipped: ['real_question', 'unverified_assumption', 'human_only', 'human_judgment'],
+        predicate: fallback?.predicate ?? '', check_by: fallback?.check_by ?? '',
+        ai_verdict: SPINE_INVARIANTS.aiVerdict,
+    };
+    const assumption_held = patch.outcome === 'held' ? true :
+        patch.outcome === 'avoided' || patch.outcome === 'partial' ? false :
+            null;
+    const merged = {
+        ...base,
+        settled_at: patch.settled_at,
+        what_happened: patch.what_happened,
+        outcome: patch.outcome,
+        outcome_source: 'user_stated',
+        assumption_held,
+        ai_verdict: SPINE_INVARIANTS.aiVerdict,
+    };
+    await atomicWriteJson(receiptPath(argusDir, id), merged);
+    return merged;
+}
+export function readReceipt(argusDir, id) {
+    try {
+        return JSON.parse(deBom(fs.readFileSync(receiptPath(argusDir, id), 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/render-receipt.js

@@ -0,0 +1,144 @@
+import { SURFACES } from './surfaces.js';
+export function renderReceipt(r, premises) {
+    const L = [];
+    const sealed = r.created_at ? r.created_at.slice(0, 10) : '—';
+    const settled = r.settled_at ? r.settled_at.slice(0, 10) : '(open)';
+    L.push('┌─ ARGUS · JUDGMENT RECEIPT ────────────────────────────────┐');
+    L.push(`  Sealed ${sealed}      Settled ${settled}`);
+    const skipped = new Set(r.skipped ?? []);
+    const show = (v, field) => (skipped.has(field) ? '— (you skipped naming this)' : wrap(v));
+    L.push('');
+    L.push('  THE REAL QUESTION');
+    L.push(`    ${show(r.real_question, 'real_question')}`);
+    L.push('  THE UNVERIFIED ASSUMPTION');
+    const assumptionSkipped = skipped.has('unverified_assumption');
+    if (assumptionSkipped && premises?.headline) {
+        // The premise set is canonical — a tracked load-bearing premise stands in
+        // for a skipped seal-time field (plan v5 §5.4).
+        L.push(`    ${wrap(premises.headline)}`);
+    }
+    else {
+        L.push(`    ${show(r.unverified_assumption, 'unverified_assumption')}`);
+    }
+    if (premises && premises.tracked > 0) {
+        L.push(`    (+${premises.tracked} premise(s) tracked · ${premises.changed_at_recheck} changed at re-check — argus_recall view=premises)`);
+    }
+    L.push(`  HUMAN-ONLY CALL   ${show(r.human_only, 'human_only')}`);
+    L.push('  …made by          Me. (not the model)');
+    if (r.basis) {
+        L.push(`  …called as        ${r.basis}`);
+    }
+    L.push('');
+    L.push(`  YOU PREDICTED   "${wrap(r.predicate)}"   (check-by ${r.check_by})`);
+    if (r.what_happened) {
+        L.push(`  WHAT HAPPENED   ${wrap(r.what_happened)}`);
+    }
+    L.push('  ─────────────────────────────────────────────────────────');
+    L.push('  AI VERDICT ON THIS DECISION ······················  NONE');
+    L.push('  The model never graded you. Reality did.');
+    L.push('└────────────────────────────────  argus · seal → settle ⚓ ─┘');
+    return L.join('\n');
+}
+/**
+ * renderSeal — the sealing confirmation `data.seal_text` (P1-E2 = 12 §3.1).
+ *
+ * The terminal twin of the webapp's seal certificate plate (P1-A3 S4): the
+ * user's predicate as a quote block, an HONEST provenance line, the two date
+ * rows, and the "not a grade" closing — same copy family, text stage.
+ *
+ * Spine rules baked in:
+ *  - provenance is a FACT statement: 'user' → "these words are yours";
+ *    'ai_surfaced' → "Argus drafted these words — you have not yet made them
+ *    yours". Never a false ownership narrative, and never a gate (sealing
+ *    as-is stays possible).
+ *  - zero hype, and one signature: the closing anchor ⚓ at the footer — the
+ *    founder's "period mark" (2026-07-03), stamped only where a loop is tied
+ *    (seal footer, settle receipt footer). Never sprinkled elsewhere.
+ *  - the day diff comes from resolveToday's `today`, not a fresh wall clock.
+ */
+export function renderSeal(opts) {
+    const S = SURFACES[opts.locale].seal;
+    const L = [];
+    const top = '┌─ ' + S.header + ' ' + '─'.repeat(Math.max(2, 56 - S.header.length)) + '┐';
+    const bottom = '└' + '─'.repeat(Math.max(2, 54 - S.footer.length)) + '  ' + S.footer + ' ─┘';
+    L.push(top);
+    L.push('');
+    // the quote block — the user's own falsifiable sentence (continuation lines
+    // sit inside the opening quote)
+    L.push(`  "${wrap(opts.predicate, 50).split('\n    ').join('\n   ')}"`);
+    L.push('');
+    const ownerLine = `  ${opts.predicate_owner === 'user' ? S.owner_user : S.owner_ai}`;
+    const ownerTag = `(predicate_owner: ${opts.predicate_owner})`;
+    L.push(ownerLine.length >= 40 ? `${ownerLine}   ${ownerTag}` : ownerLine.padEnd(40) + ownerTag);
+    L.push('');
+    const labelWidth = Math.max(S.sealed_label.length, S.answers_label.length) + 4;
+    const days = Math.round((Date.parse(opts.check_by) - Date.parse(opts.today)) / 86400000);
+    const daysOut = Number.isFinite(days) && days > 0 ? `   ${S.days_out(days)}` : '';
+    L.push(`  ${S.sealed_label.padEnd(labelWidth)}${opts.sealed_on}`);
+    L.push(`  ${S.answers_label.padEnd(labelWidth)}${opts.check_by}${daysOut}`);
+    L.push('');
+    L.push(`  ${S.closing[0]}`);
+    L.push(`  ${S.closing[1]}`);
+    L.push('');
+    L.push(bottom);
+    return L.join('\n');
+}
+const WAKE_TOP = 5; // per-group visible lines — the due_premises TOP=5 convention
+export function renderWake(contracts, stats, today, locale, 
+/** YYYY-MM-DD of the oldest ledger event (LedgerState.oldest_ts). */
+recordSince) {
+    const W = SURFACES[locale].wake;
+    const WIDTH = 60;
+    const byCheckBy = (a, b) => (a.check_by || '9999-99-99') < (b.check_by || '9999-99-99') ? -1 : 1;
+    const sealed = contracts.filter((c) => c.status === 'sealed').sort(byCheckBy);
+    const settled = contracts.filter((c) => c.status === 'settled').sort(byCheckBy);
+    const overdue = sealed.filter((c) => c.check_by && c.check_by <= today);
+    const waiting = sealed.filter((c) => !c.check_by || c.check_by > today);
+    const mmdd = (d) => (d && d.length >= 10 ? d.slice(5, 10) : d || '—');
+    const label = (c) => {
+        const raw = (c.predicate || c.text || '').replace(/\s+/g, ' ').trim();
+        return raw.length > 24 ? raw.slice(0, 23) + '…' : raw;
+    };
+    const idCol = (id) => (id.length > 10 ? id.slice(0, 9) + '…' : id).padEnd(10);
+    const L = [];
+    const headText = W.header + ' ';
+    const countText = ' ' + W.counts(contracts.length, sealed.length, settled.length) + ' ';
+    L.push('┌─ ' + headText + '─'.repeat(Math.max(2, WIDTH - 5 - headText.length - countText.length)) + countText + '─┐');
+    const pushGroup = (rows, head, line, hint) => {
+        if (rows.length === 0)
+            return;
+        L.push('');
+        L.push(hint ? `  ${head}`.padEnd(WIDTH - 2 - hint.length) + hint : `  ${head}`);
+        for (const c of rows.slice(0, WAKE_TOP))
+            L.push(`    ${line(c)}`);
+        if (rows.length > WAKE_TOP)
+            L.push(`    ${W.more(rows.length - WAKE_TOP)}`);
+    };
+    pushGroup(overdue, W.overdue_group(overdue.length), (c) => {
+        const days = Math.max(0, Math.round((Date.parse(today) - Date.parse(c.check_by)) / 86400000));
+        return `${idCol(c.id)} "${label(c)}"   ${mmdd(c.check_by)} · ${W.days_past(days)}`;
+    }, W.overdue_hint);
+    pushGroup(waiting, W.waiting_group(waiting.length), (c) => `${idCol(c.id)} "${label(c)}"   ${W.answer_on(mmdd(c.check_by))}`);
+    pushGroup(settled, W.settled_group(settled.length, stats.held, stats.avoided, stats.partial), (c) => `${idCol(c.id)} ${(c.outcome || '—').padEnd(9)} ${mmdd(c.settled_on || c.check_by)}   "${label(c)}"`);
+    L.push('');
+    const foot = recordSince ? ' ' + W.record_since(recordSince) + ' ' : '';
+    L.push('└' + '─'.repeat(Math.max(2, WIDTH - 2 - foot.length)) + foot + '─┘');
+    return L.join('\n');
+}
+function wrap(s, width = 54) {
+    const words = s.split(/\s+/);
+    const lines = [];
+    let cur = '';
+    for (const w of words) {
+        if ((cur + ' ' + w).trim().length > width) {
+            lines.push(cur.trim());
+            cur = w;
+        }
+        else {
+            cur += ' ' + w;
+        }
+    }
+    if (cur.trim())
+        lines.push(cur.trim());
+    return lines.join('\n    ');
+}

package/dist/lib/resolve-contract.js

@@ -0,0 +1,17 @@
+import { replayLedger } from './ledger-replay.js';
+import { deriveState } from './state-machine.js';
+import { receiptPath } from './layout.js';
+import { readReceipt } from './receipt.js';
+export function resolveContract(argusDir, id, today) {
+    const ledger = replayLedger(argusDir, today);
+    const entry = ledger.contracts.get(id);
+    return {
+        id,
+        state: deriveState(entry, today),
+        entry,
+        predicate: entry?.predicate,
+        check_by: entry?.check_by,
+        receiptPath: receiptPath(argusDir, id),
+        receipt: readReceipt(argusDir, id),
+    };
+}

package/dist/lib/resolve-today.js

@@ -0,0 +1,47 @@
+/**
+ * Deterministic "today" (blueprint §3.5 / addendum M4 + N).
+ *
+ * The old `localToday()` read `new Date()` local fields, so DUE computation
+ * depended on the server's local timezone and ignored every override. This
+ * replaces it with one source: an explicit override wins, else a fixed tz
+ * (ARGUS_TZ env, default UTC) formats the wall clock once per request.
+ *
+ * `Date.now()` is the only ambient time read; everything downstream takes the
+ * resulting YYYY-MM-DD string so it is fully testable.
+ */
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export function resolveToday(opts) {
+    const override = opts?.override;
+    if (typeof override === 'string' && DATE_RE.test(override))
+        return override;
+    const tz = opts?.tz || process.env['ARGUS_TZ'] || 'UTC';
+    return formatInTz(new Date(), tz);
+}
+function formatInTz(d, tz) {
+    try {
+        // en-CA yields YYYY-MM-DD; timeZone applies the fixed zone deterministically.
+        const fmt = new Intl.DateTimeFormat('en-CA', {
+            timeZone: tz,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        });
+        const parts = fmt.format(d); // "2026-07-01"
+        if (DATE_RE.test(parts))
+            return parts;
+    }
+    catch {
+        // invalid tz — fall through to UTC
+    }
+    return d.toISOString().slice(0, 10);
+}
+export function asDate(value) {
+    if (typeof value !== 'string')
+        return null;
+    const m = value.match(/(\d{4})-(\d{2})-(\d{2})/);
+    return m ? `${m[1]}-${m[2]}-${m[3]}` : null;
+}
+export function isFutureDate(check, today) {
+    const c = asDate(check);
+    return !!c && c > today;
+}

package/dist/lib/review/ids.js

@@ -0,0 +1,29 @@
+/**
+ * Deterministic ids + fingerprints for the review pipeline.
+ *
+ * Fingerprints are deterministic (same text → same hash) so we can cache
+ * analysis and detect version drift when a user re-uploads a document. Ids that
+ * must be unique per object use the app's generateId(); ids that must be stable
+ * across re-runs (units, claims) derive from content via djb2 — the same hash
+ * the codebase already uses for stablePredicateId.
+ */
+/** djb2 — stable, fast, non-cryptographic. Matches decision-contract.ts. */
+export function djb2(input) {
+    let hash = 5381;
+    for (let i = 0; i < input.length; i++) {
+        hash = ((hash << 5) + hash + input.charCodeAt(i)) & 0xffffffff;
+    }
+    // unsigned hex
+    return (hash >>> 0).toString(16);
+}
+/** Normalizes whitespace so trivial reformatting doesn't change the fingerprint. */
+export function normalizeForFingerprint(text) {
+    return text.replace(/\r\n/g, '\n').replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+export function fingerprint(text) {
+    return djb2(normalizeForFingerprint(text));
+}
+/** Stable id for a content-derived object (unit/claim), scoped by a prefix. */
+export function stableId(prefix, ...parts) {
+    return `${prefix}_${djb2(parts.join('
'))}`;
+}

package/dist/lib/review/index.js

@@ -0,0 +1,18 @@
+/**
+ * Argus review core — ported verbatim from the webapp's src/lib/review so the
+ * MCP and the webapp share ONE ingest / anchoring / reviewability / routing /
+ * prompt brain (design doc §"웹앱과 MCP는 같은 Judgment Receipt"). The only
+ * difference is the `.js` import extensions NodeNext requires. A drift guard
+ * (webapp review-mcp-drift.test.ts) fails CI if the two copies diverge.
+ *
+ * NOT ported: llm-adapter.ts + pipeline.ts. In the MCP the host agent IS the
+ * model, so the tool hands it the SSOT prompts instead of calling an LLM itself.
+ */
+export * from './schema.js';
+export { ingest } from './ingest.js';
+export { scoreReviewability } from './reviewability.js';
+export { LENSES, getLens, ALL_LENS_IDS, LENS_VERSION } from './lenses.js';
+export { routeLenses, applies } from './routing.js';
+export { buildExtractionPrompt, buildLensPrompt, buildSynthesisPrompt, renderUnits } from './prompts.js';
+export { receiptToMarkdown } from './render.js';
+export { fingerprint, stableId, djb2 } from './ids.js';

package/dist/lib/review/ingest.js

@@ -0,0 +1,294 @@
+/**
+ * Artifact-first ingestion: every input normalizes into ONE CanonicalArtifact
+ * before analysis (design doc §"입력 아키텍처: Artifact-first Ingestion").
+ *
+ * Support tiers (design doc §"MVP가 여전히 크다"):
+ *  - Tier 0 (full): paste, markdown, txt, llm_answer, transcript, pr_diff.
+ *    Real structural extraction with line/char/section anchors.
+ *  - Tier 1/2 (data-model only): pdf, docx, pptx. The schema accepts them from
+ *    day one, but until a real parser is wired we degrade HONESTLY to
+ *    `unsupported` with a recovery hint — never a confident fake review.
+ *    A caller that already has extracted text (a parser, or the MCP host) can
+ *    pass `pre_extracted` and it flows through the same anchored pipeline.
+ *
+ * The honesty rule (design doc §"실패 UX"): a low/unsupported extraction is a
+ * first-class state that reaches the UI, not a swallowed error.
+ */
+import { fingerprint, stableId } from './ids.js';
+const TIER0 = ['paste', 'markdown', 'txt', 'llm_answer', 'transcript', 'pr_diff'];
+const BINARY = ['pdf', 'docx', 'pptx'];
+export function ingest(input) {
+    const privacy_mode = input.privacy_mode ?? 'receipt_only';
+    const title = (input.title || '').trim() || defaultTitle(input.source_kind);
+    // Pre-anchored units from a real parser (pdf pages / pptx slides): trust the
+    // parser's page/slide numbers rather than re-flattening to text.
+    if (input.pre_extracted_units && input.pre_extracted_units.length > 0) {
+        return fromUnits(input, title, privacy_mode);
+    }
+    // Binary format with no extracted text → honest degrade, data model intact.
+    if (BINARY.includes(input.source_kind) && !input.pre_extracted && !input.text) {
+        return degradedArtifact(input.source_kind, title, privacy_mode);
+    }
+    const text = (input.pre_extracted ?? input.text ?? '').replace(/\r\n/g, '\n');
+    if (!text.trim()) {
+        return degradedArtifact(input.source_kind, title, privacy_mode, 'empty');
+    }
+    const isDeck = input.source_kind === 'pptx';
+    const units = input.source_kind === 'transcript'
+        ? extractTranscript(text)
+        : extractStructured(text, isDeck);
+    const fp = fingerprint(text);
+    // Extraction quality: Tier-0 text is high; binary-but-pre-extracted is medium
+    // (we trust the caller's parser but can't verify layout fidelity).
+    const quality = input.extraction_quality ?? (TIER0.includes(input.source_kind) ? 'high' : 'medium');
+    const notes = [...(input.extraction_notes ?? [])];
+    if (BINARY.includes(input.source_kind) && notes.length === 0) {
+        notes.push(input.source_kind === 'pptx'
+            ? '이 deck은 슬라이드 텍스트와 순서를 기준으로 검수했습니다. 차트/이미지 해석은 제한적입니다.'
+            : '텍스트를 기준으로 검수했습니다. 표/이미지 일부는 분석에서 빠질 수 있습니다.');
+    }
+    return {
+        artifact_id: `art_${fp}`,
+        source_kind: input.source_kind,
+        source_title: title,
+        source_fingerprint: fp,
+        extraction_quality: quality,
+        privacy_mode,
+        units,
+        detected_structure: {
+            page_count: undefined,
+            slide_count: isDeck ? countKind(units, 'slide_title') || undefined : undefined,
+            section_count: countKind(units, 'heading') || undefined,
+            heading_count: countKind(units, 'heading') || undefined,
+            table_count: countKind(units, 'table') || undefined,
+            is_deck: isDeck,
+        },
+        extraction_notes: notes,
+        source_caps: input.source_caps,
+    };
+}
+/**
+ * Build a CanonicalArtifact from a parser's already-anchored units (pdf pages /
+ * pptx slides). The parser carries page/slide numbers that a flattened-text
+ * re-extraction would lose, so we keep them verbatim and only derive structure.
+ */
+function fromUnits(input, title, privacy_mode) {
+    const units = input.pre_extracted_units;
+    const joined = units.map((u) => u.text).join('\n');
+    const fp = fingerprint(joined || title);
+    const isDeck = input.source_kind === 'pptx' || units.some((u) => u.source_anchor.slide !== undefined);
+    const pages = new Set();
+    const slides = new Set();
+    for (const u of units) {
+        if (u.source_anchor.page !== undefined)
+            pages.add(u.source_anchor.page);
+        if (u.source_anchor.slide !== undefined)
+            slides.add(u.source_anchor.slide);
+    }
+    const notes = [...(input.extraction_notes ?? [])];
+    if (notes.length === 0) {
+        notes.push(isDeck
+            ? '이 deck은 슬라이드 텍스트와 순서를 기준으로 검수했습니다. 차트/이미지 해석은 제한적입니다.'
+            : '텍스트를 기준으로 검수했습니다. 표/이미지 일부는 분석에서 빠질 수 있습니다.');
+    }
+    return {
+        artifact_id: `art_${fp}`,
+        source_kind: input.source_kind,
+        source_title: title,
+        source_fingerprint: fp,
+        extraction_quality: input.extraction_quality ?? 'medium',
+        privacy_mode,
+        units,
+        detected_structure: {
+            page_count: pages.size || undefined,
+            slide_count: slides.size || undefined,
+            section_count: countKind(units, 'heading') || undefined,
+            heading_count: countKind(units, 'heading') || undefined,
+            table_count: countKind(units, 'table') || undefined,
+            is_deck: isDeck,
+        },
+        extraction_notes: notes,
+        source_caps: input.source_caps,
+    };
+}
+function defaultTitle(kind) {
+    const map = {
+        paste: '붙여넣은 문서',
+        markdown: 'Markdown 문서',
+        txt: '텍스트 문서',
+        pdf: 'PDF 문서',
+        docx: 'DOCX 문서',
+        pptx: '슬라이드 덱',
+        transcript: '회의록',
+        mcp_file: '파일',
+        pr_diff: 'PR diff',
+        llm_answer: 'AI 답변',
+    };
+    return map[kind];
+}
+function degradedArtifact(kind, title, privacy_mode, reason = 'unsupported') {
+    const note = reason === 'empty'
+        ? '문서에서 텍스트를 찾지 못했습니다.'
+        : kind === 'pdf'
+            ? '이 PDF는 아직 자동 텍스트 추출을 지원하지 않습니다. 본문 텍스트를 붙여넣으면 검수할 수 있습니다.'
+            : kind === 'pptx'
+                ? '이 deck은 아직 자동 추출을 지원하지 않습니다. 슬라이드 텍스트를 붙여넣으면 검수할 수 있습니다.'
+                : '이 파일은 아직 자동 텍스트 추출을 지원하지 않습니다. 본문을 붙여넣어 주세요.';
+    return {
+        artifact_id: `art_${stableId(kind, title, reason)}`,
+        source_kind: kind,
+        source_title: title,
+        source_fingerprint: stableId('fp', kind, title),
+        extraction_quality: 'unsupported',
+        privacy_mode,
+        units: [],
+        detected_structure: { is_deck: kind === 'pptx' },
+        extraction_notes: [note],
+    };
+}
+function countKind(units, kind) {
+    return units.filter((u) => u.kind === kind).length;
+}
+function extractStructured(text, isDeck) {
+    const lines = text.split('\n');
+    const blocks = [];
+    const sectionStack = [];
+    // char offset of the start of each line
+    const lineOffsets = [];
+    let running = 0;
+    for (const line of lines) {
+        lineOffsets.push(running);
+        running += line.length + 1; // + newline
+    }
+    let paragraphBuf = [];
+    let paraStartLine = 0;
+    const flushParagraph = (endLine) => {
+        const joined = paragraphBuf.join('\n').trim();
+        if (joined) {
+            blocks.push(makeBlock('paragraph', joined, paraStartLine, endLine, lineOffsets, lines, currentPath(sectionStack)));
+        }
+        paragraphBuf = [];
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const line = raw.trim();
+        // Deck slide separator (--- / ===): a boundary only; the slide's title and
+        // body are captured by the heading/paragraph branches below.
+        if (isDeck && /^(-{3,}|={3,})$/.test(line)) {
+            flushParagraph(i - 1);
+            continue;
+        }
+        if (!line) {
+            flushParagraph(i - 1);
+            continue;
+        }
+        // Heading
+        const h = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (h) {
+            flushParagraph(i - 1);
+            const level = h[1].length;
+            const titleText = h[2].trim();
+            while (sectionStack.length && sectionStack[sectionStack.length - 1].level >= level) {
+                sectionStack.pop();
+            }
+            const path = currentPath(sectionStack);
+            const kind = isDeck ? 'slide_title' : 'heading';
+            blocks.push(makeBlock(kind, titleText, i, i, lineOffsets, lines, path));
+            sectionStack.push({ level, title: titleText });
+            continue;
+        }
+        // Bullet
+        if (/^([-*+]|\d+[.)])\s+/.test(line)) {
+            flushParagraph(i - 1);
+            const bulletText = line.replace(/^([-*+]|\d+[.)])\s+/, '');
+            const kind = isDeck ? 'slide_body' : 'bullet';
+            blocks.push(makeBlock(kind, bulletText, i, i, lineOffsets, lines, currentPath(sectionStack)));
+            continue;
+        }
+        // Blockquote
+        if (line.startsWith('>')) {
+            flushParagraph(i - 1);
+            blocks.push(makeBlock('quote', line.replace(/^>\s?/, ''), i, i, lineOffsets, lines, currentPath(sectionStack)));
+            continue;
+        }
+        // Table row
+        if (line.includes('|') && line.replace(/[^|]/g, '').length >= 2) {
+            flushParagraph(i - 1);
+            // skip markdown separator rows (|---|---|)
+            if (!/^\|?[\s:|-]+\|?$/.test(line)) {
+                blocks.push(makeBlock('table', line, i, i, lineOffsets, lines, currentPath(sectionStack)));
+            }
+            continue;
+        }
+        // Paragraph accumulation
+        if (paragraphBuf.length === 0)
+            paraStartLine = i;
+        paragraphBuf.push(raw);
+    }
+    flushParagraph(lines.length - 1);
+    let paraIndex = 0;
+    return blocks.map((b) => {
+        const anchor = {
+            line_start: b.line_start + 1, // 1-based for humans
+            line_end: b.line_end + 1,
+            char_start: b.char_start,
+            char_end: b.char_end,
+            section_path: b.section_path.length ? b.section_path : undefined,
+        };
+        if (b.kind === 'paragraph')
+            anchor.paragraph_index = paraIndex++;
+        if (isDeck && (b.kind === 'slide_title' || b.kind === 'slide_body')) {
+            anchor.slide = slideNumberFor(blocks, b);
+        }
+        return {
+            unit_id: stableId('u', b.kind, b.char_start, b.text.slice(0, 40)),
+            kind: b.kind,
+            text: b.text,
+            source_anchor: anchor,
+            confidence: 1,
+        };
+    });
+}
+function slideNumberFor(blocks, target) {
+    let n = 0;
+    for (const b of blocks) {
+        if (b.kind === 'slide_title')
+            n++;
+        if (b === target)
+            return Math.max(1, n);
+    }
+    return Math.max(1, n);
+}
+function makeBlock(kind, text, lineStart, lineEnd, lineOffsets, lines, section_path) {
+    const safeEnd = Math.max(lineStart, lineEnd);
+    const char_start = lineOffsets[lineStart] ?? 0;
+    const lastLen = (lines[safeEnd] ?? '').length;
+    const char_end = (lineOffsets[safeEnd] ?? char_start) + lastLen;
+    return { kind, text, line_start: lineStart, line_end: safeEnd, char_start, char_end, section_path };
+}
+function currentPath(stack) {
+    return stack.map((s) => s.title);
+}
+// ---------------------------------------------------------------------------
+// Transcript extraction: one unit per speaker turn.
+// ---------------------------------------------------------------------------
+function extractTranscript(text) {
+    const lines = text.split('\n');
+    const units = [];
+    let offset = 0;
+    lines.forEach((line, i) => {
+        const trimmed = line.trim();
+        const start = offset;
+        offset += line.length + 1;
+        if (!trimmed)
+            return;
+        units.push({
+            unit_id: stableId('u', 'turn', start, trimmed.slice(0, 40)),
+            kind: 'transcript_turn',
+            text: trimmed,
+            source_anchor: { line_start: i + 1, line_end: i + 1, char_start: start, char_end: start + line.length },
+            confidence: 1,
+        });
+    });
+    return units;
+}