@bevel-software/platform-core-backend 0.11.1 → 0.12.0

package/src/modules/workspace/file-readers/extract-pptx.ts

@@ -0,0 +1,302 @@
+import AdmZip from 'adm-zip';
+import type { ExtractResult } from './doc-extract.types.js';
+import {
+  MAX_DOC_TOTAL_BYTES,
+  attrByLocalName,
+  decodeXmlEntities,
+  localBlocks,
+  localElementBlocks,
+  localName,
+  paragraphRunText,
+  zipEntryOversize,
+} from './ooxml-text.js';
+
+/**
+ * Extract the text of a `.pptx` (PowerPoint) deck.
+ *
+ * Slides live at `ppt/slides/slideN.xml`; each is emitted under a `[slide N]`
+ * marker line, in the PRESENTATION's slide order — `ppt/presentation.xml`'s
+ * `<p:sldIdLst>`, resolved through its rels part (see
+ * `slideOrderFromPresentation`) — with numeric filename order as the fallback
+ * when the package has no readable list. Speaker notes
+ * follow their slide under `[slide N notes]` when non-empty. A slide's notes
+ * part is resolved through the slide's RELATIONSHIPS part (the `_rels` twin of
+ * the slide part's own NAME, relationship type ending `notesSlide`) — the
+ * package is free to number notes parts differently from slides — with the
+ * `notesSlideN.xml` convention as the fallback when the slide has no rels
+ * part at all. Within a slide, each `<a:p>` paragraph is a line;
+ * `<a:t>` runs concatenate with no separator (runs split mid-word).
+ *
+ * Bounded: every entry's DECLARED uncompressed size is checked before
+ * inflation (see `zipEntryOversize`), and the parts read for one deck may not
+ * exceed `MAX_DOC_TOTAL_BYTES` in total — over either bound is a typed
+ * failure, never an allocation.
+ */
+export function extractPptx(bytes: Buffer): ExtractResult {
+  let slides: Map<number, SlidePart>;
+  let notesBySlide: Map<number, string>;
+  let presOrder: string[] | undefined;
+  try {
+    const zip = new AdmZip(bytes);
+    const budget = { remaining: MAX_DOC_TOTAL_BYTES };
+    slides = collectNumbered(zip, /^ppt\/slides\/slide(\d+)\.xml$/, budget);
+    notesBySlide = collectNotes(zip, slides, budget);
+    presOrder = slideOrderFromPresentation(zip, budget);
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a .pptx (${(err as Error).message})` };
+  }
+  if (slides.size === 0) {
+    return { ok: false, message: 'could not be parsed as a .pptx (no ppt/slides/slideN.xml inside the archive)' };
+  }
+
+  // Emission order: the presentation's own slide list when it resolves to
+  // selected parts, numeric filename order otherwise (parts the list does not
+  // name follow it, in filename order). When the LIST orders the deck, the
+  // markers number POSITIONS in it — what a viewer calls slide 1 — because a
+  // reordered deck's part filenames no longer mean anything positional.
+  const byFilename = [...slides.keys()].sort((a, b) => a - b);
+  let order = byFilename;
+  let positional = false;
+  if (presOrder !== undefined) {
+    const numByName = new Map<string, number>();
+    for (const [n, slide] of slides) numByName.set(slide.name, n);
+    const seen = new Set<number>();
+    const fromList: number[] = [];
+    for (const name of presOrder) {
+      const n = numByName.get(name);
+      if (n !== undefined && !seen.has(n)) {
+        seen.add(n);
+        fromList.push(n);
+      }
+    }
+    if (fromList.length > 0) {
+      order = [...fromList, ...byFilename.filter((n) => !seen.has(n))];
+      positional = true;
+    }
+  }
+
+  const lines: string[] = [];
+  let anyNotes = false;
+  order.forEach((n, i) => {
+    const label = positional ? i + 1 : n;
+    lines.push(`[slide ${label}]`);
+    lines.push(...paragraphLines(slides.get(n)!.xml));
+    const notesXml = notesBySlide.get(n);
+    const noteLines = notesXml !== undefined ? paragraphLines(notesXml) : [];
+    if (noteLines.length > 0) {
+      anyNotes = true;
+      lines.push(`[slide ${label} notes]`);
+      lines.push(...noteLines);
+    }
+  });
+  return {
+    ok: true,
+    summary: `${slides.size} slide${slides.size === 1 ? '' : 's'}${anyNotes ? ' + notes' : ''}; layout, images and formatting omitted`,
+    text: lines.join('\n'),
+  };
+}
+
+/** Non-empty paragraph texts of one slide/notes part, in document order. */
+function paragraphLines(xml: string): string[] {
+  const out: string[] = [];
+  for (const p of localBlocks(xml, 'p')) {
+    const text = paragraphRunText(p, 't');
+    if (text.trim() !== '') out.push(text);
+  }
+  return out;
+}
+
+/** Running total of uncompressed bytes one extraction may still read. */
+interface ReadBudget {
+  remaining: number;
+}
+
+/** `entry`'s bytes as UTF-8, after the per-part and aggregate bounds. Throws over either. */
+function readEntryBounded(entry: AdmZip.IZipEntry, budget: ReadBudget): string {
+  const oversize = zipEntryOversize(entry);
+  if (oversize) throw new Error(oversize);
+  budget.remaining -= entry.header.size;
+  if (budget.remaining < 0) {
+    throw new Error(`the archive's parts exceed the ${MAX_DOC_TOTAL_BYTES}-byte (200 MB) total extraction limit`);
+  }
+  return entry.getData().toString('utf8');
+}
+
+/** The part CHOSEN for a slide number: its name as well as its bytes. */
+interface SlidePart {
+  /** Full part name, e.g. `ppt/slides/slide01.xml`. */
+  name: string;
+  xml: string;
+}
+
+/**
+ * Entries matching `re` (capture 1 = number), decoded as UTF-8, keyed by
+ * number. Two part names can parse to the SAME number (`slide1.xml` and
+ * `slide01.xml`); the winner is the FIRST in ascending part-name order —
+ * deterministic regardless of zip entry order, and the same policy as the
+ * browser twin (`pptxOutline.ts`), so viewer and `read_file` agree. Losing
+ * duplicates are never inflated (no budget charge).
+ *
+ * The winner's NAME rides along with its bytes because everything else about
+ * a slide hangs off the part name, not the number: see `collectNotes`.
+ */
+function collectNumbered(zip: AdmZip, re: RegExp, budget: ReadBudget): Map<number, SlidePart> {
+  const matched: Array<[number, string, AdmZip.IZipEntry]> = [];
+  for (const entry of zip.getEntries()) {
+    const m = re.exec(entry.entryName);
+    if (!m) continue;
+    // A crafted name can spell a number past 2^53 (or Infinity): distinct
+    // parts would collide in the map and one would silently vanish.
+    const n = parseInt(m[1], 10);
+    if (Number.isSafeInteger(n)) matched.push([n, entry.entryName, entry]);
+  }
+  // A zip may list the SAME part name twice. Sorting by name leaves those two
+  // in archive order, so which one wins depends on how the file was written —
+  // and two archives with identical parts would extract differently. A part
+  // claimed twice is not a part this reader can resolve, so it is dropped.
+  const claims = new Map<string, number>();
+  for (const [, name] of matched) claims.set(name, (claims.get(name) ?? 0) + 1);
+  const unique = matched.filter(([, name]) => claims.get(name) === 1);
+  unique.sort((a, b) => (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+  const out = new Map<number, SlidePart>();
+  for (const [n, name, entry] of unique) {
+    if (!out.has(n)) out.set(n, { name, xml: readEntryBounded(entry, budget) });
+  }
+  return out;
+}
+
+const NOTES_REL_TYPE_SUFFIX = '/notesSlide';
+const SLIDE_REL_TYPE_SUFFIX = '/slide';
+
+/**
+ * The value of the attribute whose LOCAL name is `want` AND that carries a
+ * namespace prefix. `<p:sldId>` holds both its own `id` and the relationship
+ * reference `r:id`; plain local-name matching answers with whichever is
+ * written first, so the relationship id must be the PREFIXED one.
+ */
+function prefixedAttrByLocalName(attributes: Record<string, string>, want: string): string | undefined {
+  for (const [key, value] of Object.entries(attributes)) {
+    if (key === 'xmlns' || key.startsWith('xmlns:')) continue;
+    if (key.includes(':') && localName(key) === want) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Slide part names in PRESENTATION order: `ppt/presentation.xml`'s
+ * `<p:sldIdLst>` entries, each `r:id` resolved through the presentation's own
+ * rels part — or undefined when the package has no readable list. Reordering
+ * slides in PowerPoint rewrites the sldIdLst and leaves the part names alone,
+ * so `slide1.xml` need not be the deck's first slide; the numeric filename
+ * sort is only the fallback for packages without the list.
+ */
+function slideOrderFromPresentation(zip: AdmZip, budget: ReadBudget): string[] | undefined {
+  const rels = zip.getEntry('ppt/_rels/presentation.xml.rels');
+  const pres = zip.getEntry('ppt/presentation.xml');
+  if (!rels || !pres) return undefined;
+  const targetById = new Map<string, string>();
+  for (const rel of localElementBlocks(readEntryBounded(rels, budget), ['Relationship'])) {
+    const type = attrByLocalName(rel.attributes, 'Type');
+    if (type === undefined || !type.endsWith(SLIDE_REL_TYPE_SUFFIX)) continue;
+    const id = attrByLocalName(rel.attributes, 'Id');
+    // Targets are RAW in the rels (see `notesTargetFromRels`) and relative to
+    // the presentation part's directory.
+    const target = attrByLocalName(rel.attributes, 'Target');
+    if (id !== undefined && target !== undefined) {
+      targetById.set(id, resolveRelTarget('ppt', decodeXmlEntities(target)));
+    }
+  }
+  if (targetById.size === 0) return undefined;
+  const list = localBlocks(readEntryBounded(pres, budget), 'sldIdLst')[0];
+  if (list === undefined) return undefined;
+  const order: string[] = [];
+  for (const sld of localElementBlocks(list, ['sldId'])) {
+    const rid = prefixedAttrByLocalName(sld.attributes, 'id');
+    const target = rid !== undefined ? targetById.get(rid) : undefined;
+    if (target !== undefined) order.push(target);
+  }
+  return order.length > 0 ? order : undefined;
+}
+
+/**
+ * The OPC relationships part of `partName` — `dir/_rels/base.rels`. Derived
+ * from the part NAME, never from the slide number: when a deck ships both
+ * `slide1.xml` and `slide01.xml`, the name-ordering rule picks `slide01.xml`,
+ * whose rels part is `slide01.xml.rels`. Rebuilding the path from the number
+ * asked for `slide1.xml.rels` — a part belonging to the OTHER file — and so
+ * either lost that slide's speaker notes or attached the losing part's.
+ */
+function relsPartName(partName: string): string {
+  const cut = partName.lastIndexOf('/');
+  return `${partName.slice(0, cut)}/_rels/${partName.slice(cut + 1)}.rels`;
+}
+
+/**
+ * The conventional notes part for a slide part — `slide01.xml` →
+ * `notesSlide01.xml`. Derived from the name for the same reason as the rels
+ * path, so a zero-padded deck's fallback lands on the matching notes part.
+ */
+function conventionalNotesPart(partName: string): string {
+  const base = partName.slice(partName.lastIndexOf('/') + 1);
+  return `ppt/notesSlides/notes${base[0].toUpperCase()}${base.slice(1)}`;
+}
+
+/**
+ * Slide number → its notes part's XML, resolved through each slide's `.rels`
+ * part; the conventional-name fallback ONLY for a slide without a rels part.
+ * Both paths come from the SELECTED part's name (see `relsPartName`).
+ */
+function collectNotes(zip: AdmZip, slides: Map<number, SlidePart>, budget: ReadBudget): Map<number, string> {
+  const out = new Map<number, string>();
+  for (const [n, slide] of slides) {
+    const rels = zip.getEntry(relsPartName(slide.name));
+    let notesPart: string | undefined;
+    if (rels) {
+      const target = notesTargetFromRels(readEntryBounded(rels, budget));
+      notesPart = target !== undefined ? resolveRelTarget('ppt/slides', target) : undefined;
+    } else {
+      notesPart = conventionalNotesPart(slide.name);
+    }
+    if (notesPart === undefined) continue;
+    const entry = zip.getEntry(notesPart);
+    if (entry) out.set(n, readEntryBounded(entry, budget));
+  }
+  return out;
+}
+
+/**
+ * The Target of the first `notesSlide`-typed Relationship in a rels part, or
+ * undefined.
+ *
+ * Read by the parser: matched on the element's LOCAL name, so a producer that
+ * binds the relationships namespace to a prefix (`<r:Relationship r:Type=…>`)
+ * is read like any other — and a `<Relationship>`-looking fragment written
+ * inside a COMMENT or a CDATA section is text, not live metadata pointing the
+ * notes lookup at a part of its author's choosing.
+ */
+export function notesTargetFromRels(relsXml: string): string | undefined {
+  for (const rel of localElementBlocks(relsXml, ['Relationship'])) {
+    const type = attrByLocalName(rel.attributes, 'Type');
+    if (type !== undefined && type.endsWith(NOTES_REL_TYPE_SUFFIX)) {
+      // Attribute values are RAW here (the block reader does not decode), and a
+      // part name may legally contain `&`, written `&amp;` in the rels.
+      const target = attrByLocalName(rel.attributes, 'Target');
+      return target !== undefined ? decodeXmlEntities(target) : undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Resolve an OPC relationship Target against the part's base directory. */
+export function resolveRelTarget(baseDir: string, target: string): string {
+  const parts = target.startsWith('/')
+    ? target.slice(1).split('/')
+    : [...baseDir.split('/'), ...target.split('/')];
+  const out: string[] = [];
+  for (const p of parts) {
+    if (p === '' || p === '.') continue;
+    if (p === '..') out.pop();
+    else out.push(p);
+  }
+  return out.join('/');
+}

package/src/modules/workspace/file-readers/extract-xlsx.ts

@@ -0,0 +1,96 @@
+import AdmZip from 'adm-zip';
+import * as XLSX from 'xlsx';
+import type { ExtractResult } from './doc-extract.types.js';
+import { MAX_DOC_TOTAL_BYTES, zipEntryOversize } from './ooxml-text.js';
+
+/**
+ * Per-sheet extraction caps. A worksheet's declared range can be enormous
+ * (a stray cell at XFD1048576 makes the range 16k x 1M); the caps bound the
+ * text an agent gets to something readable, and the extraction SAYS when it
+ * truncated (a `[sheet truncated …]` line right under the sheet marker).
+ */
+const MAX_ROWS_PER_SHEET = 10_000;
+const MAX_COLS_PER_SHEET = 200;
+
+/**
+ * Extract a `.xlsx` (Excel) workbook via SheetJS: per sheet a `[sheet: Name]`
+ * marker, then the rows as tab-separated values (each cell's FORMATTED value,
+ * e.g. dates as dates; tabs/newlines INSIDE a cell become single spaces so a
+ * cell's line break never reads as a row boundary), with trailing empty rows
+ * trimmed.
+ */
+export function extractXlsx(bytes: Buffer): ExtractResult {
+  // A real .xlsx is a zip. Check the signature OURSELVES because SheetJS
+  // helpfully falls back to parsing arbitrary bytes as CSV/HTML — which would
+  // turn a corrupt upload into confident nonsense instead of an honest error.
+  if (bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b) {
+    return { ok: false, message: 'could not be parsed as a .xlsx (not a zip archive)' };
+  }
+  // Zip-bomb bound BEFORE SheetJS inflates anything: the central directory
+  // declares every entry's uncompressed size, so per-part (50 MB) and
+  // aggregate (200 MB) limits cost one directory scan. A zip AdmZip cannot
+  // read falls through — SheetJS then reports its own parse failure.
+  try {
+    const zip = new AdmZip(bytes);
+    let total = 0;
+    for (const entry of zip.getEntries()) {
+      const oversize = zipEntryOversize(entry);
+      if (oversize) return { ok: false, message: `could not be extracted as a .xlsx (${oversize})` };
+      total += entry.header.size;
+      if (total > MAX_DOC_TOTAL_BYTES) {
+        return {
+          ok: false,
+          message: `could not be extracted as a .xlsx (the archive's parts exceed the ${MAX_DOC_TOTAL_BYTES}-byte (200 MB) total extraction limit)`,
+        };
+      }
+    }
+  } catch {
+    // not AdmZip-readable — let SheetJS produce the typed parse failure below
+  }
+  let wb: XLSX.WorkBook;
+  try {
+    wb = XLSX.read(bytes, { type: 'buffer' });
+  } catch (err) {
+    return { ok: false, message: `could not be parsed as a .xlsx (${(err as Error).message})` };
+  }
+
+  const lines: string[] = [];
+  for (const name of wb.SheetNames) {
+    // Control separators become spaces — the same rule as the ods extractor:
+    // a crafted workbook's sheet name holding a tab or newline would split
+    // the `[sheet: …]` marker's own line and break grep line numbers.
+    lines.push(`[sheet: ${name.replace(/[\t\n\r]+/g, ' ')}]`);
+    const ws = wb.Sheets[name];
+    const ref = ws?.['!ref'];
+    if (!ws || !ref) continue; // empty sheet — marker only
+    const range = XLSX.utils.decode_range(ref);
+    const truncated: string[] = [];
+    if (range.e.r - range.s.r + 1 > MAX_ROWS_PER_SHEET) {
+      range.e.r = range.s.r + MAX_ROWS_PER_SHEET - 1;
+      truncated.push(`first ${MAX_ROWS_PER_SHEET} rows`);
+    }
+    if (range.e.c - range.s.c + 1 > MAX_COLS_PER_SHEET) {
+      range.e.c = range.s.c + MAX_COLS_PER_SHEET - 1;
+      truncated.push(`first ${MAX_COLS_PER_SHEET} columns`);
+    }
+    if (truncated.length > 0) {
+      lines.push(`[sheet truncated to the ${truncated.join(' and ')}]`);
+      ws['!ref'] = XLSX.utils.encode_range(range);
+    }
+    // Rows via sheet_to_json (formatted cell text, one array per worksheet
+    // row): sheet_to_csv CSV-quotes a cell containing a line break, so
+    // splitting its output on newlines turned ONE worksheet row into several
+    // extracted rows. Cell-internal tabs/newlines become single spaces
+    // instead — the same one-line-per-row contract as the ods extractor.
+    const rows = XLSX.utils
+      .sheet_to_json<unknown[]>(ws, { header: 1, raw: false, defval: '', blankrows: true })
+      .map((cells) => cells.map((c) => String(c).replace(/[\t\n\r]+/g, ' ')).join('\t'));
+    while (rows.length > 0 && rows[rows.length - 1].replace(/\t/g, '') === '') rows.pop();
+    lines.push(...rows);
+  }
+  return {
+    ok: true,
+    summary: `${wb.SheetNames.length} sheet${wb.SheetNames.length === 1 ? '' : 's'}, rows as tab-separated values; formulas, formatting and charts omitted`,
+    text: lines.join('\n'),
+  };
+}

package/src/modules/workspace/file-readers/extraction-cache.ts

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { ExtractedDoc } from './doc-extract.types.js';
+
+/**
+ * Git BLOB sha of `bytes` — sha1 over `"blob <len>\0" + bytes`, exactly what
+ * `git hash-object` computes. Chosen as the cache key because the workspace is
+ * a git clone: for a clean tracked file this equals the sha `git ls-files -s`
+ * would report, WITHOUT spawning git — and because it is computed from the
+ * bytes actually read, it stays correct (it just stops matching the index)
+ * when the file is untracked or dirty. One code path, no fallback branch.
+ */
+export function gitBlobSha(bytes: Buffer): string {
+  return createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+}
+
+/** Default size bound for the on-disk extraction cache. */
+const DEFAULT_MAX_TOTAL_BYTES = 512 * 1024 * 1024; // 512MB
+
+/**
+ * On-disk cache of document extractions. The KEY is the caller's business —
+ * `DocExtractService` passes git blob sha + extension (content hash, so a
+ * re-upload of identical bytes, or the same document on another branch or
+ * path, hits the same entry; extension, so identical bytes under another
+ * FORMAT never return the wrong extractor's output). One JSON file per entry
+ * (`<key>.json` holding the `{ summary, text }`), under a dedicated root
+ * that — like the spill
+ * store's — sits BESIDE the workspaces root, never inside a workspace and
+ * never committed.
+ *
+ * Bounding: writes best-effort prune OLDEST-MTIME entries until the total
+ * size fits `maxTotalBytes` (simple LRU-ish eviction; reads don't touch
+ * mtime, so it is closer to FIFO — good enough for a cache whose entries are
+ * cheap to rebuild). The full scan is deferred until the writes since the
+ * last one could plausibly have reached the bound (see `writtenSinceScan`).
+ * Every filesystem error here is swallowed: the cache is an accelerator,
+ * never a reason for a read to fail.
+ */
+export class DocExtractionCache {
+  constructor(
+    private readonly root: string,
+    private readonly maxTotalBytes: number = DEFAULT_MAX_TOTAL_BYTES,
+  ) {}
+
+  /** The cached extraction for `sha`, or undefined on miss/corrupt entry. */
+  async get(sha: string): Promise<ExtractedDoc | undefined> {
+    try {
+      const parsed: unknown = JSON.parse(await fs.readFile(this.entryPath(sha), 'utf8'));
+      if (
+        typeof parsed === 'object' && parsed !== null &&
+        typeof (parsed as ExtractedDoc).summary === 'string' &&
+        typeof (parsed as ExtractedDoc).text === 'string'
+      ) {
+        return { summary: (parsed as ExtractedDoc).summary, text: (parsed as ExtractedDoc).text };
+      }
+      return undefined;
+    } catch {
+      return undefined; // miss, unreadable or corrupt — treated identically
+    }
+  }
+
+  /**
+   * Bytes written since the last full scan. The scan costs a `readdir` plus a
+   * `stat` per entry, and running it on EVERY cold extraction made a cache that
+   * is nowhere near its bound pay for the bound anyway. Writes are accumulated
+   * instead and the scan runs once they could plausibly have reached it.
+   */
+  private writtenSinceScan = 0;
+
+  /** Total size the last scan found (after eviction); undefined before the first scan, so the first write scans. */
+  private totalAtLastScan: number | undefined;
+
+  /** The prune in flight, so concurrent puts share ONE scan instead of racing their own. */
+  private pruning: Promise<void> | undefined;
+
+  /** Store an extraction under `sha`; prunes towards the size bound. Never throws. */
+  async put(sha: string, doc: ExtractedDoc): Promise<void> {
+    try {
+      await fs.mkdir(this.root, { recursive: true });
+      const payload = JSON.stringify({ summary: doc.summary, text: doc.text });
+      await fs.writeFile(this.entryPath(sha), payload, 'utf8');
+      this.writtenSinceScan += Buffer.byteLength(payload);
+      if (
+        this.totalAtLastScan === undefined ||
+        this.totalAtLastScan + this.writtenSinceScan > this.maxTotalBytes
+      ) {
+        this.pruning ??= this.prune().finally(() => {
+          this.pruning = undefined;
+        });
+        await this.pruning;
+      }
+    } catch {
+      // cache write failed — the extraction still returns; next read re-extracts
+    }
+  }
+
+  /**
+   * The file backing `key`, always INSIDE the cache root.
+   *
+   * The key is built from a content hash and an extension taken from a
+   * workspace path, so a path spelling `../` — or a Windows backslash — would
+   * otherwise resolve outside the root and let a read or a write reach an
+   * arbitrary file. Only the characters a real key uses survive.
+   */
+  private entryPath(key: string): string {
+    const safe = key.replace(/[^A-Za-z0-9._-]/g, '_');
+    return path.join(this.root, `${safe}.json`);
+  }
+
+  /** Delete oldest-mtime entries until the total size fits the bound. */
+  private async prune(): Promise<void> {
+    // Snapshot FIRST: a write counted before the scan starts is on disk when
+    // `readdir` runs, so the scan settles exactly those bytes. A put that
+    // lands DURING the scan keeps its count (resetting to zero discarded it,
+    // and a later put then trusted a total the scan never saw), so the next
+    // put still prunes instead of leaving the cache above the bound.
+    const scanned = this.writtenSinceScan;
+    const entries: Array<{ p: string; size: number; mtime: number }> = [];
+    let total = 0;
+    for (const name of await fs.readdir(this.root)) {
+      try {
+        const st = await fs.stat(path.join(this.root, name));
+        if (!st.isFile()) continue;
+        entries.push({ p: path.join(this.root, name), size: st.size, mtime: st.mtimeMs });
+        total += st.size;
+      } catch {
+        // vanished mid-scan — ignore
+      }
+    }
+    if (total > this.maxTotalBytes) {
+      entries.sort((a, b) => a.mtime - b.mtime);
+      for (const e of entries) {
+        if (total <= this.maxTotalBytes) break;
+        await fs.rm(e.p, { force: true });
+        total -= e.size;
+      }
+    }
+    this.totalAtLastScan = total;
+    this.writtenSinceScan -= scanned;
+  }
+}

package/src/modules/workspace/file-readers/file-reader.registry.ts

@@ -0,0 +1,45 @@
+import type { DocExtractService } from './doc-extract.service.js';
+import { DocumentReader } from './document-reader.js';
+import { EmailReader } from './email-reader.js';
+import { extractDocx } from './extract-docx.js';
+import { extractEml } from './extract-eml.js';
+import { extractMsg } from './extract-msg.js';
+import { extractOdp } from './extract-odp.js';
+import { extractOds } from './extract-ods.js';
+import { extractOdt } from './extract-odt.js';
+import { extractPdf } from './extract-pdf.js';
+import { extractPptx } from './extract-pptx.js';
+import { extractXlsx } from './extract-xlsx.js';
+import { FileReaderRegistry } from './file-reader.js';
+import { ImageReader } from './image-reader.js';
+import { LegacyOfficeReader, TextReader } from './text-reader.js';
+
+/**
+ * THE registry of file readers — the one place that says which reader owns
+ * which extension. Adding a format is one entry here (plus its reader/extract
+ * function); read_file, grep and the write-refusal all follow automatically.
+ *
+ * `docExtract` is the shared content-hash extraction cache the document
+ * readers wrap their pure extract functions with (see DocumentReader).
+ * Everything not claimed below falls back to the TextReader.
+ */
+export function createFileReaderRegistry(docExtract: DocExtractService): FileReaderRegistry {
+  return new FileReaderRegistry(
+    [
+      new DocumentReader('.docx', extractDocx, docExtract),
+      new DocumentReader('.pptx', extractPptx, docExtract),
+      new DocumentReader('.xlsx', extractXlsx, docExtract),
+      new DocumentReader('.pdf', extractPdf, docExtract),
+      new DocumentReader('.odt', extractOdt, docExtract),
+      new DocumentReader('.odp', extractOdp, docExtract),
+      new DocumentReader('.ods', extractOds, docExtract),
+      // Email files ride the same document machinery (cached extraction,
+      // greppable, not text-editable) with an email-honest write refusal.
+      new EmailReader('.eml', extractEml, docExtract),
+      new EmailReader('.msg', extractMsg, docExtract),
+      new ImageReader(),
+      new LegacyOfficeReader(),
+    ],
+    new TextReader(),
+  );
+}