create-pmos 0.197.0 → 0.198.0

package/workspace/lib/report-design.js

@@ -0,0 +1,741 @@
+'use strict';
+/* report-design.js — the report design studio's file store, fold, sanitizer and outline logic (initiative report-design-studio, PRD "Data").
+ *
+ *   paths(root, cadence)                      → { folder, design, events, samples, versions, pending, brief, rel }   <state>/reports/<cadence>/design/…
+ *   append(root, cadence, line, { actor, now }) → the line written. THE SINGLE WRITER of design.jsonl. `at` and `actor` are set here.
+ *   readEvents(root, cadence) · fold(events)  → the current state (see FOLD)
+ *   designAnswer(root, cadence, { running })  → the `design` object GET /api/report-design answers
+ *   addSample(root, cadence, input, { actor }) → { ok, sample } | { ok: false, status, error }   a file (20 MB, pdf/pptx/docx/png/jpg), a link or a report doc
+ *   writeVersion(root, cadence, html, meta)   → { ok, n, outline }   sanitizes, writes versions/D<n>.html + D<n>.json
+ *   writeBrief(root, cadence, setup, st)      → brief.md (type Reference)
+ *   sanitize(html)                            → the render with no script, no on* attribute, no javascript: and no external URL (data: images kept, one style block)
+ *   outlineOf(html)                           → [{ id, kind, title }]   the pmos-slide / pmos-sec sections, in order
+ *   formatOf(html)                            → 'deck' | 'doc'
+ *   diffOutline(reference, cycle)             → [{ id, what, slide }]   what differs from the design
+ *   cyclePaths(root, rel) · readCycle · writeCycle   <slot>.design.html / <slot>.design.json next to <slot>.md
+ *   notesOf(root, rel) · setSpeaker · pinOp   <slot>.notes.json: speaker notes, suggestions from the previous cycle, pins
+ *   ooxmlText(buffer, kind) · ooxmlThumb(buffer)   the words of a .pptx/.docx (its XML parts, read with node's zlib) and its embedded thumbnail
+ *
+ * THE LINES of design.jsonl. Every line is { ev, …, at, actor }. `actor` is the guard's actor for a press, or { by: 'pmos', via: 'job' } for a job:
+ *   describe      { text, format }                         the PM's plain words, and Deck or Document
+ *   sample        { id, name, kind, source, ext, readable } a sample was added (the file is samples/<id>.<ext>, its record samples/<id>.json)
+ *   took          { id, took, readable }                   what a job took from a sample (or that it could not read it)
+ *   turn          { text, points, base, job }              a refine turn started a job; `base` is the version it builds on
+ *   version       { n, format, turn, answer, from }        a job (or an adopted cycle) landed D<n>
+ *   accept        { n, rules }                             "This is it": D<n> is the design; brief.md is written
+ *   revert        { n }                                    the next turn builds on D<n>
+ *   error         { text, mode, slot?, sha? }              a job failed, timed out or wrote nothing usable
+ *   cycle-decision { path, slot, diff, choice }            keep | adopt | match on a cycle that differs
+ *
+ * FOLD. { description, format, samples: Map, log: [], versions: Map n → meta, current, saved, rules, errors: [] }. A torn line is skipped.
+ *
+ * THE SANITIZER parses the HTML with a small tokenizer (tags, attributes with their quoting, comments, raw-text elements) and rebuilds it from the
+ * tokens: nothing in the output is copied from a span the tokenizer did not understand, and text is re-escaped. It drops script, iframe, object, embed,
+ * frame, applet, noscript, template, base, link and meta with their content; every on* attribute; srcdoc, srcset, action and formaction; a
+ * javascript:/vbscript: value anywhere; and every URL in src/href/poster/background/data/xlink:href and CSS url() that is not a data: image (an href may
+ * also be a #fragment). CSS is de-commented and de-escaped before it is checked; @import and expression() go. Every <style> becomes ONE block.
+ *
+ * NOTHING HERE STARTS A JOB OR SENDS ANYTHING. lib/routes-report-design.js starts the report-design job and calls these writers.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const zlib = require('zlib');
+const RD = require('./report-draft.js');
+const issues = require('./issues.js');
+
+const EVENTS = Object.freeze(['describe', 'sample', 'took', 'turn', 'version', 'accept', 'revert', 'error', 'cycle-decision']);
+const FORMATS = Object.freeze(['deck', 'doc']);
+const SAMPLE_KINDS = Object.freeze(['pdf', 'pptx', 'docx', 'image', 'link', 'pmos-doc']);
+const MAX_SAMPLE_BYTES = 20 * 1024 * 1024;
+const MAX_THUMB_BYTES = 256 * 1024;
+const MAX_TEXT = 4000;
+const MAX_POINTS = 20;
+const CHOICES = Object.freeze(['keep', 'adopt', 'match']);
+const PIN_OPS = Object.freeze(['add', 'edit', 'remove', 'keep', 'dismiss']);
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const SAMPLE_ID_RE = /^s-[0-9a-f]{8}$/;
+const SLIDE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/;
+const SLOT_RE = /^\d{4}-\d{2}-\d{2}$/;
+const PMOS_ACTOR = Object.freeze({ by: 'pmos', via: 'job' });
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const str = (v) => (typeof v === 'string' ? v : '');
+const refuse = (status, error) => ({ ok: false, status, error });
+const iso = (now) => new Date(now == null ? Date.now() : now).toISOString();
+const newId = (prefix, bytes = 4) => `${prefix}-${crypto.randomBytes(bytes).toString('hex')}`;
+const sha1 = (buf) => crypto.createHash('sha1').update(buf).digest('hex');
+const clip = (s, n) => { const t = String(s == null ? '' : s).replace(/\r\n?/g, '\n').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+const oneLine = (s, n) => clip(String(s == null ? '' : s).replace(/\s+/g, ' '), n);
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${crypto.randomBytes(4).toString('hex')}`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+function readJson(file) { try { const o = JSON.parse(fs.readFileSync(file, 'utf8')); return isObj(o) ? o : null; } catch { return null; } }
+
+// ── paths ─────────────────────────────────────────────────────────────────────────────────────────────────
+function stateRel(root) { try { return RD.stateRel(root); } catch { return 'planning'; } }
+function paths(root, cadence) {
+  if (!CADENCE_RE.test(String(cadence || ''))) throw new Error('report-design: not a report id: ' + JSON.stringify(cadence));
+  const abs = path.resolve(String(root));
+  const rel = `${stateRel(abs)}/reports/${cadence}`;
+  const folder = path.join(abs, rel);
+  const design = path.join(folder, 'design');
+  return { abs, rel, folder, design, events: path.join(design, 'design.jsonl'), samples: path.join(design, 'samples'), versions: path.join(design, 'versions'),
+    pending: path.join(design, 'pending'), brief: path.join(design, 'brief.md'), briefRel: `${rel}/design/brief.md` };
+}
+
+// ── the one writer and the fold ───────────────────────────────────────────────────────────────────────────
+function append(root, cadence, line, { actor, now } = {}) {
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`report-design: unknown event ${JSON.stringify(line && line.ev)}`);
+  const p = paths(root, cadence);
+  const out = { ...line, at: iso(now), actor: isObj(actor) ? { by: str(actor.by), via: str(actor.via) } : { ...PMOS_ACTOR } };
+  fs.mkdirSync(p.design, { recursive: true });
+  fs.appendFileSync(p.events, JSON.stringify(out) + '\n');
+  return out;
+}
+function readEvents(root, cadence) {
+  let text = '';
+  try { text = fs.readFileSync(paths(root, cadence).events, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (!raw.trim()) continue;
+    try { const l = JSON.parse(raw); if (isObj(l) && EVENTS.includes(l.ev)) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+const whoOf = (l) => (l.actor && l.actor.by === 'pmos' ? 'pmos' : 'you');
+
+function fold(events) {
+  const st = { description: null, format: null, samples: new Map(), log: [], versions: new Map(), current: null, saved: null, rules: null, errors: [], decisions: [], turns: 0 };
+  for (const l of events) {
+    if (l.ev === 'describe') {
+      st.description = str(l.text) || st.description;
+      if (FORMATS.includes(l.format)) st.format = l.format;
+      st.log.push({ at: l.at, who: 'you', kind: 'describe', text: str(l.text) });
+    } else if (l.ev === 'sample') {
+      st.samples.set(l.id, { id: l.id, name: str(l.name), kind: l.kind, source: str(l.source), ext: str(l.ext), took: null, readable: l.readable !== false, at: l.at });
+      st.log.push({ at: l.at, who: 'you', kind: 'sample', text: str(l.name), sample: l.id });
+    } else if (l.ev === 'took') {
+      const s = st.samples.get(l.id);
+      if (s) { if (typeof l.took === 'string' && l.took) s.took = l.took; if (typeof l.readable === 'boolean') s.readable = l.readable; }
+    } else if (l.ev === 'turn') {
+      st.turns++;
+      st.log.push({ at: l.at, who: 'you', kind: 'turn', text: str(l.text), ...(Array.isArray(l.points) && l.points.length ? { points: l.points } : {}) });
+    } else if (l.ev === 'version') {
+      st.versions.set(l.n, { n: l.n, format: l.format, made_at: l.at, turn: str(l.turn), from: l.from || 'turn' });
+      st.current = l.n;
+      if (FORMATS.includes(l.format) && !st.format) st.format = l.format;
+      st.log.push({ at: l.at, who: 'pmos', kind: 'version', text: str(l.answer) || `Made D${l.n}.`, version: l.n });
+    } else if (l.ev === 'accept') {
+      st.saved = { version: l.n, at: l.at };
+      if (isObj(l.rules)) st.rules = l.rules;
+      st.log.push({ at: l.at, who: whoOf(l), kind: 'accept', text: `Saved D${l.n} as the design.`, version: l.n });
+    } else if (l.ev === 'revert') {
+      if (st.versions.has(l.n)) st.current = l.n;
+      st.log.push({ at: l.at, who: 'you', kind: 'revert', text: `Back to D${l.n}. The next turn builds on it.`, version: l.n });
+    } else if (l.ev === 'error') {
+      st.errors.push({ at: l.at, text: str(l.text), mode: l.mode || null, slot: l.slot || null, sha: l.sha || null });
+      st.log.push({ at: l.at, who: 'pmos', kind: 'error', text: str(l.text) });
+    } else if (l.ev === 'cycle-decision') {
+      st.decisions.push({ path: l.path, slot: l.slot, diff: l.diff, choice: l.choice, at: l.at });
+    }
+  }
+  return st;
+}
+const stateOf = (root, cadence) => fold(readEvents(root, cadence));
+
+// ── versions ──────────────────────────────────────────────────────────────────────────────────────────────
+function versionMeta(root, cadence, n) { return readJson(path.join(paths(root, cadence).versions, `D${n}.json`)); }
+function versionHtml(root, cadence, n) { try { return fs.readFileSync(path.join(paths(root, cadence).versions, `D${n}.html`), 'utf8'); } catch { return null; } }
+const nextN = (st) => (st.versions.size ? Math.max(...st.versions.keys()) : 0) + 1;
+
+/** Sanitize, then write D<n>.html and D<n>.json and append the version line. → { ok, n, outline } | refusal */
+function writeVersion(root, cadence, html, { turn, answer, rules, from, actor, now } = {}) {
+  const clean = sanitize(html);
+  const outline = outlineOf(clean);
+  if (!outline.length) return refuse(422, 'the render has no pmos-slide or pmos-sec section');
+  const p = paths(root, cadence);
+  const st = stateOf(root, cadence);
+  const n = nextN(st);
+  const format = formatOf(clean);
+  const madeAt = iso(now);
+  const meta = { n, format, made_at: madeAt, turn: clip(turn, MAX_TEXT), answer: clip(answer, MAX_TEXT), from: from || 'turn', outline, rules: cleanRules(rules) };
+  writeAtomic(path.join(p.versions, `D${n}.html`), clean);
+  writeAtomic(path.join(p.versions, `D${n}.json`), JSON.stringify(meta, null, 2) + '\n');
+  append(root, cadence, { ev: 'version', n, format, turn: meta.turn, answer: meta.answer, from: meta.from }, { actor, now });
+  return { ok: true, n, outline, format };
+}
+function cleanRules(r) {
+  if (!isObj(r)) return null;
+  const list = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.trim()).slice(0, 12).map((x) => oneLine(x, 300)) : []);
+  const out = { same: list(r.same), changes: list(r.changes), learned: list(r.learned) };
+  return out.same.length || out.changes.length || out.learned.length ? out : null;
+}
+/** The rules of D<n>, else of the newest earlier version that has rules. */
+function rulesFor(root, cadence, n) {
+  for (let k = n; k >= 1; k--) { const m = versionMeta(root, cadence, k); if (m && m.rules) return m.rules; }
+  return null;
+}
+
+// ── samples ───────────────────────────────────────────────────────────────────────────────────────────────
+function sniff(buf) {
+  if (buf.length >= 4 && buf.toString('latin1', 0, 4) === '%PDF') return { kind: 'pdf', ext: 'pdf' };
+  if (buf.length >= 8 && buf[0] === 0x89 && buf.toString('latin1', 1, 4) === 'PNG') return { kind: 'image', ext: 'png' };
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return { kind: 'image', ext: 'jpg' };
+  if (buf.length >= 4 && buf.readUInt32LE(0) === 0x04034b50) return { kind: 'zip', ext: 'zip' };
+  return null;
+}
+function sampleRecord(root, cadence, id) { return readJson(path.join(paths(root, cadence).samples, `${id}.json`)); }
+
+/**
+ * input: { name, kind, data: <base64> } | { link } | { doc: <repo path of a report document> }. → { ok, sample } | refusal.
+ * A .pptx or .docx also gets samples/<id>.txt (its words), which is what the job reads.
+ */
+function addSample(root, cadence, input, { actor, now } = {}) {
+  const p = paths(root, cadence);
+  const id = newId('s');
+  let rec;
+  if (typeof input.link === 'string' && input.link.trim()) {
+    const link = input.link.trim();
+    let u; try { u = new URL(link); } catch { return refuse(400, 'link must be a full address, such as https://…'); }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return refuse(400, 'link must be an http or https address');
+    if (link.length > 2000) return refuse(400, 'link is too long');
+    rec = { id, name: oneLine(input.name || u.hostname + u.pathname, 120), kind: 'link', source: link, ext: '', readable: true, thumb: null, text_file: null };
+  } else if (typeof input.doc === 'string' && input.doc.trim()) {
+    const rel = input.doc.trim().replace(/\\/g, '/');
+    if (!/(?:^|\/)reports\/(?!definitions\/)[a-z][a-z0-9-]{0,39}\/\d{4}-\d{2}-\d{2}\.md$/.test(rel)) return refuse(400, 'doc must be a report document: <state>/reports/<cadence>/<slot>.md');
+    const full = path.resolve(p.abs, rel);
+    if (!full.startsWith(p.abs + path.sep)) return refuse(404, 'outside workspace');
+    let text; try { const real = fs.realpathSync(full); if (!real.startsWith(fs.realpathSync(p.abs) + path.sep)) return refuse(404, 'outside workspace'); text = fs.readFileSync(real, 'utf8'); } catch { return refuse(404, 'no such report document'); }
+    fs.mkdirSync(p.samples, { recursive: true });
+    writeAtomic(path.join(p.samples, `${id}.md`), text);
+    const fm = /^---\r?\n[\s\S]*?\btitle:\s*["']?([^\n"']+)/.exec(text);
+    rec = { id, name: oneLine(input.name || (fm ? fm[1] : rel.split('/').slice(-2).join(' ')), 120), kind: 'pmos-doc', source: rel, ext: 'md', readable: true, thumb: null, text_file: null };
+  } else {
+    const kind = str(input.kind);
+    if (!['pdf', 'pptx', 'docx', 'image'].includes(kind)) return refuse(400, 'kind must be pdf, pptx, docx or image (or send a link, or a report doc)');
+    if (typeof input.data !== 'string' || !input.data) return refuse(400, 'data (the file, base64) is required');
+    const b64 = input.data.replace(/^data:[^,]*,/, '');
+    if (Math.floor(b64.length * 3 / 4) > MAX_SAMPLE_BYTES + 4) return refuse(413, 'a sample is at most 20 MB');
+    const buf = Buffer.from(b64, 'base64');
+    if (!buf.length) return refuse(400, 'data is empty or not base64');
+    if (buf.length > MAX_SAMPLE_BYTES) return refuse(413, 'a sample is at most 20 MB');
+    const s = sniff(buf);
+    const want = kind === 'image' ? 'image' : kind === 'pdf' ? 'pdf' : 'zip';
+    if (!s || s.kind !== want) return refuse(415, kind === 'image' ? 'an image sample must be a PNG or a JPG' : `the file is not a ${kind === 'pdf' ? 'PDF' : '.' + kind}`);
+    const ext = kind === 'image' ? s.ext : kind;
+    fs.mkdirSync(p.samples, { recursive: true });
+    writeAtomic(path.join(p.samples, `${id}.${ext}`), buf);
+    let thumb = null; let textFile = null; let readable = true;
+    if (kind === 'image' && buf.length <= MAX_THUMB_BYTES) thumb = `data:image/${ext === 'jpg' ? 'jpeg' : 'png'};base64,${buf.toString('base64')}`;
+    if (kind === 'pptx' || kind === 'docx') {
+      let words = '';
+      try { words = ooxmlText(buf, kind); } catch { words = ''; }
+      if (words.trim()) { writeAtomic(path.join(p.samples, `${id}.txt`), words); textFile = `${id}.txt`; } else readable = false;
+      try { thumb = ooxmlThumb(buf); } catch { thumb = null; }
+    }
+    rec = { id, name: oneLine(input.name || `${kind} sample`, 120), kind, source: 'upload', ext, bytes: buf.length, readable, thumb, text_file: textFile };
+  }
+  writeAtomic(path.join(p.samples, `${id}.json`), JSON.stringify({ ...rec, took: null, added_at: iso(now) }, null, 2) + '\n');
+  append(root, cadence, { ev: 'sample', id, name: rec.name, kind: rec.kind, source: rec.source, ext: rec.ext, readable: rec.readable }, { actor, now });
+  return { ok: true, sample: sampleOut(rec) };
+}
+function sampleOut(s) {
+  return { id: s.id, name: s.name, kind: s.kind, source: s.source, took: s.took || null, thumb: typeof s.thumb === 'string' && s.thumb.startsWith('data:image/') ? s.thumb : null, readable: s.readable !== false };
+}
+/** Record what a job took from a sample (also kept in samples/<id>.json). */
+function recordTook(root, cadence, id, took, readable, { now } = {}) {
+  if (!SAMPLE_ID_RE.test(String(id))) return false;
+  const p = paths(root, cadence);
+  const rec = sampleRecord(root, cadence, id);
+  if (!rec) return false;
+  const t = typeof took === 'string' ? oneLine(took, 400) : null;
+  const rd = typeof readable === 'boolean' ? readable : undefined;
+  writeAtomic(path.join(p.samples, `${id}.json`), JSON.stringify({ ...rec, took: t || rec.took || null, ...(rd === undefined ? {} : { readable: rd }) }, null, 2) + '\n');
+  append(root, cadence, { ev: 'took', id, took: t, ...(rd === undefined ? {} : { readable: rd }) }, { now });
+  return true;
+}
+/** The file the job reads for a sample: the pdf or image itself, the extracted words of a .pptx/.docx, the copy of a report doc; null for a link. */
+function sampleReadPath(root, cadence, s) {
+  const p = paths(root, cadence);
+  if (s.kind === 'link') return null;
+  if (s.kind === 'pptx' || s.kind === 'docx') { const f = path.join(p.samples, `${s.id}.txt`); return fs.existsSync(f) ? f : null; }
+  const f = path.join(p.samples, `${s.id}.${s.ext}`);
+  return fs.existsSync(f) ? f : null;
+}
+
+// ── the GET answer ────────────────────────────────────────────────────────────────────────────────────────
+function designAnswer(root, cadence, { running } = {}) {
+  const st = stateOf(root, cadence);
+  const samples = [...st.samples.values()].map((s) => {
+    const rec = sampleRecord(root, cadence, s.id) || {};
+    return sampleOut({ ...s, thumb: rec.thumb || null, took: s.took || rec.took || null });
+  });
+  const versions = [...st.versions.values()].sort((a, b) => a.n - b.n).map((v) => {
+    const m = versionMeta(root, cadence, v.n) || {};
+    return { n: v.n, format: m.format || v.format || 'deck', made_at: m.made_at || v.made_at, turn: m.turn != null ? m.turn : v.turn, outline: Array.isArray(m.outline) ? m.outline : [] };
+  });
+  const state = st.saved ? 'saved' : (st.description || st.samples.size || st.versions.size || st.turns) ? 'draft' : 'none';
+  const cur = st.current != null ? versions.find((v) => v.n === st.current) : null;
+  return {
+    state, format: (cur && cur.format) || st.format || 'deck',
+    description: st.description, samples, log: st.log, versions,
+    current: st.current, saved: st.saved, rules: st.rules || (st.saved ? rulesFor(root, cadence, st.saved.version) : null),
+    running: running || null,
+  };
+}
+
+// ── brief.md ──────────────────────────────────────────────────────────────────────────────────────────────
+const yq = (s) => JSON.stringify(String(s == null ? '' : s));
+function writeBrief(root, cadence, setup, { now } = {}) {
+  const st = stateOf(root, cadence);
+  if (!st.saved) return refuse(409, 'no design is saved yet');
+  const n = st.saved.version;
+  const meta = versionMeta(root, cadence, n) || {};
+  const rules = st.rules || rulesFor(root, cadence, n) || { same: [], changes: [], learned: [] };
+  const name = (setup && setup.name) || cadence;
+  const day = iso(now).slice(0, 10);
+  const lines = ['---', 'type: Reference', `title: ${yq('Report design: ' + name)}`, `timestamp: ${day}`, '---', '', `# Report design: ${name}`, '',
+    `The saved design of the ${name} report. PMOS renders each cycle to match it: the same order, look and slide kinds, with that cycle's data. It is a brief, not a template.`, '',
+    `- Format: ${meta.format === 'doc' ? 'document' : 'slide deck'}`, `- Reference version: D${n} (versions/D${n}.html), saved ${st.saved.at.slice(0, 10)}`, '',
+    '## Description', '', st.description ? st.description : 'No description was given.', '', '## Samples', ''];
+  const samples = [...st.samples.values()];
+  if (!samples.length) lines.push('No samples.');
+  for (const s of samples) lines.push(`- ${s.name} (${s.kind}${s.kind === 'link' || s.kind === 'pmos-doc' ? ', ' + s.source : ''}): ${s.took ? 'PMOS took ' + s.took : (s.readable ? 'nothing taken yet' : 'could not be read')}`);
+  lines.push('', '## Reference outline', '');
+  for (const o of (Array.isArray(meta.outline) ? meta.outline : [])) lines.push(`- ${o.id} (${o.kind || 'slide'}): ${o.title || ''}`);
+  const sec = (h, list) => { lines.push('', `## ${h}`, ''); if (!list || !list.length) lines.push('None written yet.'); else for (const x of list) lines.push(`- ${x}`); };
+  sec('Keeps the same each cycle', rules.same);
+  sec('Changes each cycle', rules.changes);
+  sec('Learned from your turns', rules.learned);
+  lines.push('');
+  writeAtomic(paths(root, cadence).brief, lines.join('\n'));
+  return { ok: true, path: paths(root, cadence).briefRel };
+}
+
+// ── the sanitizer ─────────────────────────────────────────────────────────────────────────────────────────
+const RAW_TEXT = new Set(['script', 'style', 'textarea', 'title', 'xmp', 'iframe', 'noembed', 'noframes', 'noscript', 'plaintext']);
+const DROP_ALL = new Set(['script', 'iframe', 'object', 'embed', 'frame', 'frameset', 'applet', 'noscript', 'noembed', 'noframes', 'template', 'base', 'link', 'meta', 'portal', 'param', 'xmp', 'plaintext']);
+const UNWRAP = new Set(['form', 'html', 'head', 'body']);
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr', 'frame', 'keygen']);
+const URL_ATTRS = new Set(['src', 'href', 'xlink:href', 'poster', 'background', 'data', 'cite', 'longdesc', 'codebase', 'archive', 'usemap', 'icon', 'profile', 'lowsrc', 'dynsrc', 'action', 'formaction']);
+const DROP_ATTRS = new Set(['srcdoc', 'srcset', 'imagesrcset', 'action', 'formaction', 'ping', 'manifest', 'http-equiv', 'autofocus', 'codebase', 'archive', 'classid']);
+const NAMED = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", colon: ':', tab: '\t', newline: '\n', nbsp: String.fromCharCode(0xa0), sol: '/', lpar: '(', rpar: ')', period: '.', comma: ',' };
+
+function decodeEntities(s) {
+  return String(s).replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);?/gi, (m, e) => {
+    if (e[0] === '#') { const cp = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10); return Number.isFinite(cp) && cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : ''; }
+    const v = NAMED[e.toLowerCase()];
+    return v != null ? v : m;
+  });
+}
+const escText = (s) => String(s).replace(/&(?!(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);)/gi, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** A URL as a browser reads it: entities decoded, control characters and whitespace removed, lower-case. */
+const invisible = (c) => c <= 0x20 || (c >= 0x7f && c <= 0x9f) || (c >= 0x200b && c <= 0x200f) || c === 0x2028 || c === 0x2029 || c === 0xfeff;
+const normUrl = (v) => { let o = ""; for (const ch of decodeEntities(v)) if (!invisible(ch.codePointAt(0))) o += ch; return o.toLowerCase(); };
+const DATA_IMAGE_RE = /^data:image\/(png|jpe?g|gif|webp|avif|bmp|svg\+xml)[;,]/;
+const isDataImage = (u) => DATA_IMAGE_RE.test(normUrl(u));
+
+/** Tokens: { t: 'text', v } | { t: 'start', name, attrs: [[name, value|null]], self } | { t: 'end', name } | { t: 'raw', name, v } (after a raw start). */
+function tokenize(html) {
+  const s = String(html == null ? '' : html);
+  const n = s.length;
+  const out = [];
+  let i = 0;
+  const START = /<([a-zA-Z][a-zA-Z0-9:-]*)(?=[\s/>]|$)/y;
+  const END = /<\/([a-zA-Z][a-zA-Z0-9:-]*)[^>]*>/y;
+  const ws = (c) => c === ' ' || c === '\n' || c === '\t' || c === '\r' || c === '\f';
+  while (i < n) {
+    const lt = s.indexOf('<', i);
+    if (lt < 0) { out.push({ t: 'text', v: s.slice(i) }); break; }
+    if (lt > i) out.push({ t: 'text', v: s.slice(i, lt) });
+    i = lt;
+    if (s.startsWith('<!--', i)) { const e = s.indexOf('-->', i + 4); i = e < 0 ? n : e + 3; continue; }
+    if (s[i + 1] === '!' || s[i + 1] === '?') { const e = s.indexOf('>', i); i = e < 0 ? n : e + 1; continue; }
+    if (s[i + 1] === '/') {
+      END.lastIndex = i;
+      const m = END.exec(s);
+      if (m) { out.push({ t: 'end', name: m[1].toLowerCase(), raw: m[1] }); i = END.lastIndex; continue; }
+      const e = s.indexOf('>', i);   // `</ junk>` is a bogus comment to a browser
+      if (s[i + 2] && !/[a-zA-Z]/.test(s[i + 2]) && e >= 0) { i = e + 1; continue; }
+      out.push({ t: 'text', v: '<' }); i++; continue;
+    }
+    START.lastIndex = i;
+    const m = START.exec(s);
+    if (!m) { out.push({ t: 'text', v: '<' }); i++; continue; }
+    let j = START.lastIndex;
+    const attrs = [];
+    let self = false; let closed = false;
+    while (j < n) {
+      while (j < n && (ws(s[j]) || s[j] === '/')) { if (s[j] === '/' && s[j + 1] === '>') self = true; j++; }
+      if (j >= n) break;
+      if (s[j] === '>') { j++; closed = true; break; }
+      let k = j;
+      while (k < n && !ws(s[k]) && s[k] !== '/' && s[k] !== '>' && (k === j || s[k] !== '=')) k++;
+      const an = s.slice(j, k);
+      j = k;
+      while (j < n && ws(s[j])) j++;
+      let val = null;
+      if (s[j] === '=') {
+        j++;
+        while (j < n && ws(s[j])) j++;
+        if (s[j] === '"' || s[j] === "'") { const q = s[j]; const e = s.indexOf(q, j + 1); val = s.slice(j + 1, e < 0 ? n : e); j = e < 0 ? n : e + 1; }
+        else { let k2 = j; while (k2 < n && !ws(s[k2]) && s[k2] !== '>') k2++; val = s.slice(j, k2); j = k2; }
+      }
+      attrs.push([an, val]);
+    }
+    if (!closed) break;   // an unterminated tag at the end is dropped, with what follows it
+    const name = m[1].toLowerCase();
+    out.push({ t: 'start', name, raw: m[1], attrs, self });
+    i = j;
+    if (RAW_TEXT.has(name) && !self) {
+      const close = new RegExp(`</${name}(?=[\\s/>])`, 'ig');
+      close.lastIndex = i;
+      const c = close.exec(s);
+      const end = c ? c.index : n;
+      out.push({ t: 'raw', name, v: s.slice(i, end) });
+      if (c) { const gt = s.indexOf('>', end); out.push({ t: 'end', name, raw: name }); i = gt < 0 ? n : gt + 1; } else i = n;
+    }
+  }
+  return out;
+}
+
+/** CSS with no external fetch, no script and no way out of its block. */
+function cleanCss(css) {
+  let c = String(css == null ? '' : css);
+  c = c.replace(/\/\*[\s\S]*?(\*\/|$)/g, ' ');
+  c = c.replace(/\\([0-9a-fA-F]{1,6})[ \t\r\n\f]?/g, (m, h) => { const cp = parseInt(h, 16); return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : ''; }).replace(/\\(.)/g, '$1').replace(/\\$/g, '');
+  c = c.replace(/@import[^;{}]*;?/gi, '').replace(/@namespace[^;{}]*;?/gi, '');
+  c = c.replace(/expression\s*\(/gi, 'none(').replace(/behaviou?r\s*:/gi, 'x-behavior:').replace(/-moz-binding/gi, 'x-binding').replace(/javascript\s*:/gi, '').replace(/vbscript\s*:/gi, '');
+  c = c.replace(/url\s*\(\s*(?:"([^"]*)"|'([^']*)'|([^)]*))\s*\)/gi, (m, a, b, d) => { const u = a != null ? a : b != null ? b : d || ''; return isDataImage(u) ? `url("${u.trim().replace(/"/g, '%22')}")` : 'none'; });
+  c = c.replace(/(["'])\s*(?:https?:|\/\/|ftp:)[^"']*\1/gi, '""');
+  c = c.replace(/\b(?:src|image|image-set|-webkit-image-set|cross-fade|element)\s*\(\s*["']?\s*(?:https?:|\/\/)[^)]*\)/gi, 'none');
+  return c.replace(/</g, '\\3c ').replace(/>/g, '\\3e ');
+}
+
+function cleanAttrs(tag, attrs) {
+  const out = [];
+  const seen = new Set();
+  for (const [rawName, rawVal] of attrs) {
+    const name = String(rawName).toLowerCase();
+    if (!/^[a-z_:][-a-z0-9_:.]*$/.test(name) || seen.has(name)) continue;
+    if (name.startsWith('on') || DROP_ATTRS.has(name)) continue;
+    const val = rawVal == null ? '' : decodeEntities(rawVal);
+    const norm = normUrl(val);
+    if (/(?:^|[^a-z])(?:javascript|vbscript|livescript):/.test(norm) || norm.startsWith('javascript:')) continue;
+    let keep = val;
+    if (name === 'style') { keep = cleanCss(val); }
+    else if (URL_ATTRS.has(name)) {
+      if (name === 'href' || name === 'xlink:href' || name === 'usemap') { if (!(norm.startsWith('#') || DATA_IMAGE_RE.test(norm))) continue; }
+      else if (!DATA_IMAGE_RE.test(norm)) continue;
+    } else if (!name.startsWith('data-') && /^(?:https?:|\/\/)/.test(norm) && ['to', 'from', 'values', 'by', 'filter', 'mask', 'clip-path', 'fill', 'stroke', 'marker-start', 'marker-mid', 'marker-end', 'cursor'].includes(name)) continue;
+    else if (!name.startsWith('data-') && /url\s*\(/i.test(val)) keep = cleanCss(val);
+    seen.add(name);
+    out.push(rawVal == null ? ` ${rawName}` : ` ${rawName}="${escAttr(keep)}"`);
+  }
+  return out.join('');
+}
+
+function sanitize(html) {
+  const toks = tokenize(html);
+  const out = [];
+  const css = [];
+  let styleAt = -1;
+  let skip = null;   // { name, depth }: inside a dropped element
+  for (let k = 0; k < toks.length; k++) {
+    const t = toks[k];
+    if (skip) {
+      if (t.t === 'start' && t.name === skip.name && !t.self && !VOID.has(t.name)) skip.depth++;
+      else if (t.t === 'end' && t.name === skip.name) { skip.depth--; if (skip.depth === 0) skip = null; }
+      continue;
+    }
+    if (t.t === 'text') { out.push(escText(t.v)); continue; }
+    if (t.t === 'raw') {
+      if (t.name === 'style') css.push(t.v);
+      else if (t.name === 'textarea' || t.name === 'title') out.push(escText(decodeEntities(t.v)));
+      continue;
+    }
+    if (t.t === 'start') {
+      if (DROP_ALL.has(t.name)) {
+        if (!t.self && !VOID.has(t.name) && !RAW_TEXT.has(t.name)) skip = { name: t.name, depth: 1 };
+        else if (RAW_TEXT.has(t.name) && toks[k + 1] && toks[k + 1].t === 'raw') { k++; if (toks[k + 1] && toks[k + 1].t === 'end' && toks[k + 1].name === t.name) k++; }
+        continue;
+      }
+      if (t.name === 'style') { if (styleAt < 0) { styleAt = out.length; out.push(''); } continue; }
+      if (UNWRAP.has(t.name)) continue;
+      out.push(`<${t.raw}${cleanAttrs(t.name, t.attrs)}${t.self ? ' /' : ''}>`);
+      continue;
+    }
+    if (t.t === 'end') {
+      if (DROP_ALL.has(t.name) || UNWRAP.has(t.name) || t.name === 'style' || VOID.has(t.name)) continue;
+      out.push(`</${t.raw}>`);
+    }
+  }
+  const block = css.length ? `<style>${cleanCss(css.join('\n'))}</style>` : '';
+  if (styleAt >= 0) out[styleAt] = block;
+  else if (block) out.unshift(block);
+  return out.join('');
+}
+
+// ── the outline and its diff ──────────────────────────────────────────────────────────────────────────────
+function outlineOf(html) {
+  const out = [];
+  const seen = new Set();
+  for (const t of tokenize(html)) {
+    if (t.t !== 'start' || t.name !== 'section') continue;
+    const a = {};
+    for (const [n, v] of t.attrs) { const k = String(n).toLowerCase(); if (!(k in a)) a[k] = v == null ? '' : decodeEntities(v); }
+    const cls = String(a.class || '').split(/\s+/);
+    const isSlide = cls.includes('pmos-slide'); const isSec = cls.includes('pmos-sec');
+    if (!isSlide && !isSec) continue;
+    let id = oneLine(isSlide ? a['data-slide-id'] : a['data-sec-id'], 80) || `${isSlide ? 'slide' : 'sec'}-${out.length + 1}`;
+    while (seen.has(id)) id += '-2';
+    seen.add(id);
+    out.push({ id, kind: oneLine(a['data-kind'], 40) || (isSlide ? 'slide' : 'section'), title: oneLine(a['data-title'], 160) });
+  }
+  return out;
+}
+function formatOf(html) { return /class\s*=\s*["']?[^"'>]*\bpmos-slide\b/i.test(String(html || '')) ? 'deck' : 'doc'; }
+
+/** What differs between the reference outline and a cycle's: a slide added or missing, a kind changed, the order changed. Titles carry data and are not compared. */
+function diffOutline(reference, cycle) {
+  const ref = Array.isArray(reference) ? reference : [];
+  const cyc = Array.isArray(cycle) ? cycle : [];
+  const R = new Map(ref.map((o) => [o.id, o]));
+  const C = new Map(cyc.map((o) => [o.id, o]));
+  const out = [];
+  const label = (o) => (o.title ? `"${o.title}"` : o.id);
+  for (const o of cyc) if (!R.has(o.id)) out.push({ id: `added:${o.id}`, what: `${label(o)} (${o.kind}) is new this cycle; the design has no such slide.`, slide: o.id });
+  for (const o of ref) if (!C.has(o.id)) out.push({ id: `missing:${o.id}`, what: `${label(o)} (${o.kind}) from the design is not in this cycle.`, slide: o.id });
+  for (const o of cyc) { const r = R.get(o.id); if (r && r.kind !== o.kind) out.push({ id: `kind:${o.id}`, what: `${label(o)} is a ${o.kind} slide; the design has a ${r.kind} slide here.`, slide: o.id }); }
+  const a = ref.filter((o) => C.has(o.id)).map((o) => o.id);
+  const b = cyc.filter((o) => R.has(o.id)).map((o) => o.id);
+  if (a.join('\u0000') !== b.join('\u0000')) {
+    const first = b.find((id, i) => id !== a[i]);
+    out.push({ id: 'order', what: 'The order of the slides differs from the design.', slide: first || null });
+  }
+  return out;
+}
+
+// ── a cycle's render ──────────────────────────────────────────────────────────────────────────────────────
+/** rel = <state>/reports/<cadence>/<slot>.md → { abs, cadence, slot, html, json, notes, md } | null */
+function cyclePaths(root, rel) {
+  const r = String(rel || '').replace(/\\/g, '/');
+  const m = /(?:^|\/)reports\/([a-z][a-z0-9-]{0,39})\/(\d{4}-\d{2}-\d{2})\.md$/.exec(r);
+  if (!m || m[1] === 'definitions') return null;
+  const abs = path.resolve(String(root));
+  const md = path.resolve(abs, r);
+  if (!md.startsWith(abs + path.sep)) return null;
+  const base = md.slice(0, -3);
+  return { abs, rel: path.relative(abs, md).split(path.sep).join('/'), cadence: m[1], slot: m[2], md, html: base + '.design.html', json: base + '.design.json', notes: base + '.notes.json' };
+}
+function readCycle(root, rel) { const c = cyclePaths(root, rel); return c ? readJson(c.json) : null; }
+function isIssuedSlot(root, cadence, slot) { try { return issues.isIssued(issues.readIssues(path.resolve(String(root))), cadence, slot); } catch { return false; } }
+function docSha(file) { try { return sha1(fs.readFileSync(file)); } catch { return null; } }
+
+/** Write a cycle's render: sanitize, outline, compare with the design version it was rendered for. Keeps the decisions already made. */
+function writeCycle(root, rel, html, { designVersion, mode, sha, now } = {}) {
+  const c = cyclePaths(root, rel);
+  if (!c) return refuse(400, 'not a report document');
+  const clean = sanitize(html);
+  const outline = outlineOf(clean);
+  if (!outline.length) return refuse(422, 'the render has no pmos-slide or pmos-sec section');
+  const ref = versionMeta(root, c.cadence, designVersion) || {};
+  const differences = diffOutline(ref.outline || [], outline);
+  const prev = readJson(c.json) || {};
+  const rec = { design_version: designVersion, format: formatOf(clean), outline, differences, decisions: Array.isArray(prev.decisions) ? prev.decisions : [],
+    rendered_at: iso(now), mode: mode || 'cycle', source_sha: sha || docSha(c.md) };
+  writeAtomic(c.html, clean);
+  writeAtomic(c.json, JSON.stringify(rec, null, 2) + '\n');
+  return { ok: true, cycle: rec };
+}
+/** Record a decision on the cycle file (and, for adopt, point it at the new version and recompute what differs). */
+function decideCycle(root, rel, { diff, choice, newVersion, now } = {}) {
+  const c = cyclePaths(root, rel);
+  const rec = c ? readJson(c.json) : null;
+  if (!rec) return refuse(404, 'this cycle has no render yet');
+  const at = iso(now);
+  rec.decisions = [...(Array.isArray(rec.decisions) ? rec.decisions : []), { diff, choice, at }];
+  if (choice === 'adopt' && newVersion) {
+    rec.design_version = newVersion;
+    const ref = versionMeta(root, c.cadence, newVersion) || {};
+    rec.differences = diffOutline(ref.outline || [], rec.outline || []);
+  }
+  writeAtomic(c.json, JSON.stringify(rec, null, 2) + '\n');
+  return { ok: true, cycle: rec };
+}
+
+// ── notes ─────────────────────────────────────────────────────────────────────────────────────────────────
+function readNotesFile(file) {
+  const o = readJson(file) || {};
+  return { speaker: isObj(o.speaker) ? o.speaker : {}, pins: Array.isArray(o.pins) ? o.pins : [], cleared: Array.isArray(o.cleared) ? o.cleared : [] };
+}
+/** The nearest earlier cycle of the same report that has notes. */
+function previousCycle(root, rel) {
+  const c = cyclePaths(root, rel);
+  if (!c) return null;
+  let files = [];
+  try { files = fs.readdirSync(path.dirname(c.md)); } catch { return null; }
+  const slots = files.map((f) => /^(\d{4}-\d{2}-\d{2})\.md$/.exec(f)).filter(Boolean).map((m) => m[1]).filter((s) => s < c.slot).sort().reverse();
+  if (!slots.length) return null;
+  const relDir = path.posix.dirname(c.rel);
+  return { slot: slots[0], path: `${relDir}/${slots[0]}.md`, slots };
+}
+function notesOf(root, rel) {
+  const c = cyclePaths(root, rel);
+  if (!c) return refuse(400, 'path must be a report document: <state>/reports/<cadence>/<slot>.md');
+  const mine = readNotesFile(c.notes);
+  const suggestions = {};
+  const prev = previousCycle(root, rel);
+  if (prev) {
+    for (const slot of prev.slots) {
+      const other = readNotesFile(path.join(path.dirname(c.md), `${slot}.notes.json`));
+      for (const [id, v] of Object.entries(other.speaker)) {
+        if (!v || !str(v.text) || mine.speaker[id] || mine.cleared.includes(id) || suggestions[id]) continue;
+        suggestions[id] = { text: v.text, from_slot: slot };
+      }
+      if (Object.values(other.speaker).some((v) => v && str(v.text))) break;   // the nearest cycle that has notes is the one suggested from
+    }
+  }
+  return { ok: true, speaker: mine.speaker, suggestions, pins: mine.pins.filter((p) => p && p.state !== 'removed') };
+}
+function writeNotes(c, n) { writeAtomic(c.notes, JSON.stringify({ speaker: n.speaker, pins: n.pins, cleared: n.cleared }, null, 2) + '\n'); }
+
+/** { slide, text } ('' clears: an explicit empty note, which also hides the suggestion) | { slide, keep: true } (adopts the suggestion). */
+function setSpeaker(root, rel, { slide, text, keep } = {}, { now } = {}) {
+  const c = cyclePaths(root, rel);
+  if (!c) return refuse(400, 'path must be a report document: <state>/reports/<cadence>/<slot>.md');
+  if (!SLIDE_ID_RE.test(str(slide))) return refuse(400, 'slide must be a slide id');
+  const n = readNotesFile(c.notes);
+  if (keep === true) {
+    const sug = notesOf(root, rel).suggestions[slide];
+    if (!sug) return refuse(404, 'there is no suggestion for that slide');
+    n.speaker[slide] = { text: sug.text, at: iso(now), from_slot: sug.from_slot };
+  } else {
+    if (typeof text !== 'string') return refuse(400, 'text is required (an empty text clears the note)');
+    if (text.length > MAX_TEXT) return refuse(400, `a speaker note is at most ${MAX_TEXT} characters`);
+    // An empty text is kept as an explicit empty note: it clears the note and hides the suggestion from the previous cycle.
+    n.speaker[slide] = { text: text.trim() ? text.replace(/\r\n?/g, '\n') : '', at: iso(now) };
+  }
+  writeNotes(c, n);
+  return { ok: true, speaker: n.speaker[slide] || null };
+}
+
+/** One pin operation. → { ok, pin, op } | refusal. `by` is 'you' for a press, 'pmos' for a job's proposal. */
+function pinOp(root, rel, body, { by = 'you', now } = {}) {
+  const c = cyclePaths(root, rel);
+  if (!c) return refuse(400, 'path must be a report document: <state>/reports/<cadence>/<slot>.md');
+  const op = str(body.op);
+  if (!PIN_OPS.includes(op)) return refuse(400, `op must be one of ${PIN_OPS.join(', ')}`);
+  const n = readNotesFile(c.notes);
+  const coord = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 100 ? v : null);   // percent of the slide (or section) box
+  if (op === 'add') {
+    if (!SLIDE_ID_RE.test(str(body.slide))) return refuse(400, 'slide must be a slide id');
+    const x = coord(body.x); const y = coord(body.y);
+    if (x == null || y == null) return refuse(400, 'x and y must be numbers');
+    const text = str(body.text).trim();
+    if (!text || text.length > 1000) return refuse(400, 'text is required, at most 1000 characters');
+    const pin = { id: newId('pin'), slide: body.slide, x, y, text, by: by === 'pmos' ? 'pmos' : 'you', state: 'open', at: iso(now), ...(str(body.section).trim() ? { section: oneLine(body.section, 120) } : {}) };
+    n.pins.push(pin);
+    writeNotes(c, n);
+    return { ok: true, pin, op };
+  }
+  const pin = n.pins.find((p) => p && p.id === str(body.id) && p.state !== 'removed');
+  if (!pin) return refuse(404, 'no such pin');
+  if (op === 'edit') {
+    if (body.text !== undefined) { const text = str(body.text).trim(); if (!text || text.length > 1000) return refuse(400, 'text is required, at most 1000 characters'); pin.text = text; }
+    if (body.x !== undefined) { const x = coord(body.x); if (x == null) return refuse(400, 'x must be a number'); pin.x = x; }
+    if (body.y !== undefined) { const y = coord(body.y); if (y == null) return refuse(400, 'y must be a number'); pin.y = y; }
+    if (body.slide !== undefined) { if (!SLIDE_ID_RE.test(str(body.slide))) return refuse(400, 'slide must be a slide id'); pin.slide = body.slide; }
+    pin.edited_at = iso(now);
+  } else if (op === 'remove') pin.state = 'removed';
+  else if (op === 'keep') pin.state = 'kept';
+  else if (op === 'dismiss') pin.state = 'dismissed';
+  pin.changed_at = iso(now);
+  writeNotes(c, n);
+  return { ok: true, pin, op };
+}
+
+// ── .pptx / .docx ─────────────────────────────────────────────────────────────────────────────────────────
+/** The entries of a zip whose names pass `want`, each inflated to at most `cap` bytes. A malformed zip throws. */
+function unzipSome(buf, want, cap = 8 * 1024 * 1024) {
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= 0 && i >= buf.length - 65557; i--) if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  if (eocd < 0) throw new Error('not a zip');
+  const count = buf.readUInt16LE(eocd + 10);
+  let p = buf.readUInt32LE(eocd + 16);
+  const out = [];
+  let total = 0;
+  for (let k = 0; k < count && p + 46 <= buf.length; k++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error('bad central directory');
+    const method = buf.readUInt16LE(p + 10); const csize = buf.readUInt32LE(p + 20);
+    const nlen = buf.readUInt16LE(p + 28); const xlen = buf.readUInt16LE(p + 30); const clen = buf.readUInt16LE(p + 32); const lho = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nlen);
+    p += 46 + nlen + xlen + clen;
+    if (!want(name)) continue;
+    if (lho + 30 > buf.length || buf.readUInt32LE(lho) !== 0x04034b50) continue;
+    const start = lho + 30 + buf.readUInt16LE(lho + 26) + buf.readUInt16LE(lho + 28);
+    const body = buf.subarray(start, start + csize);
+    let data;
+    try { data = method === 8 ? zlib.inflateRawSync(body, { maxOutputLength: cap }) : method === 0 ? Buffer.from(body) : null; } catch { data = null; }
+    if (!data) continue;
+    total += data.length;
+    if (total > 4 * cap) break;
+    out.push({ name, data });
+  }
+  return out;
+}
+const xmlText = (s) => decodeEntities(String(s).replace(/<[^>]*>/g, ''));
+/** The words of a .pptx (slide by slide) or .docx (paragraph by paragraph). */
+function ooxmlText(buf, kind) {
+  if (kind === 'pptx') {
+    const slides = unzipSome(buf, (n) => /^ppt\/slides\/slide\d+\.xml$/.test(n))
+      .sort((a, b) => Number(/(\d+)\.xml$/.exec(a.name)[1]) - Number(/(\d+)\.xml$/.exec(b.name)[1]));
+    return slides.map((s, i) => {
+      const x = s.data.toString('utf8');
+      const paras = x.split(/<\/a:p>/).map((p) => (p.match(/<a:t>([\s\S]*?)<\/a:t>/g) || []).map(xmlText).join('')).filter((t) => t.trim());
+      return `--- Slide ${i + 1} ---\n${paras.join('\n')}`;
+    }).join('\n\n');
+  }
+  const doc = unzipSome(buf, (n) => n === 'word/document.xml')[0];
+  if (!doc) return '';
+  const x = doc.data.toString('utf8');
+  return x.split(/<\/w:p>/).map((p) => {
+    const t = (p.match(/<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>/g) || []).map(xmlText).join('');
+    const h = /<w:pStyle w:val="(Heading\d|Title)"/.exec(p);
+    return t.trim() ? (h ? `# ${t}` : t) : '';
+  }).filter(Boolean).join('\n');
+}
+/** The thumbnail an Office file carries (docProps/thumbnail.jpeg or .png), as a data: URL, or null. */
+function ooxmlThumb(buf) {
+  const t = unzipSome(buf, (n) => /^docProps\/thumbnail\.(jpe?g|png)$/i.test(n), MAX_THUMB_BYTES + 1)[0];
+  if (!t || t.data.length > MAX_THUMB_BYTES) return null;
+  const s = sniff(t.data);
+  if (!s || s.kind !== 'image') return null;
+  return `data:image/${s.ext === 'jpg' ? 'jpeg' : 'png'};base64,${t.data.toString('base64')}`;
+}
+
+/** The newest report document of a cadence folder (the current cycle), repository-relative, or null. */
+function currentCycle(root, cadence) {
+  const p = paths(root, cadence);
+  let files = [];
+  try { files = fs.readdirSync(p.folder); } catch { return null; }
+  const slots = files.map((f) => /^(\d{4}-\d{2}-\d{2})\.md$/.exec(f)).filter(Boolean).map((m) => m[1]).sort();
+  if (!slots.length) return null;
+  const slot = slots[slots.length - 1];
+  return { slot, path: `${p.rel}/${slot}.md`, abs: path.join(p.folder, `${slot}.md`) };
+}
+
+module.exports = {
+  EVENTS, FORMATS, SAMPLE_KINDS, MAX_SAMPLE_BYTES, CHOICES, PIN_OPS, CADENCE_RE, SLOT_RE, SLIDE_ID_RE, PMOS_ACTOR,
+  paths, append, readEvents, fold, stateOf, designAnswer, versionMeta, versionHtml, writeVersion, rulesFor, cleanRules,
+  addSample, sampleOut, sampleRecord, recordTook, sampleReadPath, writeBrief,
+  tokenize, sanitize, cleanCss, outlineOf, formatOf, diffOutline,
+  cyclePaths, readCycle, writeCycle, decideCycle, isIssuedSlot, docSha, currentCycle, previousCycle,
+  notesOf, setSpeaker, pinOp, ooxmlText, ooxmlThumb, unzipSome,
+};