@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/workspace/__tests__/write-denial.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, vi } from 'vitest';
+import { writeDenial } from '../write-denial.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+
+/**
+ * The `write-denied` answer's "may you propose this instead?" is the read
+ * gate's question, asked about the refused path AS WHAT IT IS: a folder a
+ * move or delete was judged on, or a file. A folder directly under a root is
+ * proposable where a file there is not, so the kind the refuser recorded is
+ * what decides — never a guess from the path's spelling.
+ */
+
+const KB = 'knowledge-base';
+// One of the branches the backend test config marks protected.
+const PROTECTED = 'target-company-state';
+const INPUT = { tool: 'move_file', branch: PROTECTED, userEmail: 'alice@example.com', userId: 'u1' };
+
+function gateThat(verdict: ChangeReadVerdict) {
+  const judge = vi.fn(async () => verdict);
+  const gate: IChangeReadGate = { judge, assertMayChange: vi.fn() };
+  return { gate, judge };
+}
+
+const noAccess = {} as unknown as IAccessControl;
+
+describe('writeDenial asks the read gate about the refused path as the refuser saw it', () => {
+  it('a folder refusal is judged as a folder — a new root folder is then proposable', async () => {
+    const { gate, judge } = gateThat({ allowed: true, via: 'new-top-level-folder' });
+    const err = new AccessDeniedError({
+      path: `${KB}/KnowledgeBase/Projects`,
+      eligibleRoles: ['Admin'],
+      eligibleUsers: [],
+      targetKind: 'dir',
+    });
+    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    expect(judge).toHaveBeenCalledWith(
+      'target-company-state',
+      'alice@example.com',
+      `${KB}/KnowledgeBase/Projects`,
+      'dir',
+    );
+    expect(out.status).toBe(403);
+    expect(out.details).toMatchObject({ kind: 'write-denied', canPropose: true });
+  });
+
+  it('a refusal that says nothing about its kind is judged as a file', async () => {
+    const { gate, judge } = gateThat({ allowed: false, unreadable: 'KnowledgeBase' });
+    const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/loose.md`, eligibleRoles: [], eligibleUsers: [] });
+    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    expect(judge).toHaveBeenCalledWith(expect.any(String), 'alice@example.com', `${KB}/KnowledgeBase/loose.md`, 'file');
+    expect(out.details).toMatchObject({
+      kind: 'write-denied',
+      canPropose: false,
+      cannotProposeReason: 'Proposing is not available: you cannot read this path.',
+    });
+  });
+
+  it('without a gate the read verdict alone decides, as before', async () => {
+    const accessControl = { canRead: vi.fn(async () => true) } as unknown as IAccessControl;
+    const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
+    const out = await writeDenial(err, INPUT, accessControl, KB);
+    expect(accessControl.canRead).toHaveBeenCalledWith('target-company-state', 'alice@example.com', 'KnowledgeBase/Sales/deal.md');
+    expect(out.details).toMatchObject({ kind: 'write-denied', canPropose: true });
+  });
+
+  it('a gate that cannot answer refuses to offer the route', async () => {
+    const gate: IChangeReadGate = { judge: vi.fn(async () => { throw new Error('git down'); }), assertMayChange: vi.fn() };
+    const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
+    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    expect(out.details).toMatchObject({ canPropose: false });
+    expect(out.details?.cannotProposeReason).toContain('could not be determined');
+  });
+});

package/src/modules/workspace/empty-dirs.ts

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+
+const codeOf = (err: unknown): string | undefined => (err as { code?: string } | null)?.code;
+
+/** The directory is not there (any more), or is no longer a directory. */
+const isGone = (err: unknown): boolean => codeOf(err) === 'ENOENT' || codeOf(err) === 'ENOTDIR';
+
+/**
+ * Recursively remove empty directories under `absoluteDir`, bottom-up, then
+ * remove `absoluteDir` itself if it ends up empty. A directory is removed only
+ * if it contains nothing at the moment it's visited, so any file a concurrent
+ * writer dropped in mid-delete — and every parent directory on its path —
+ * survives. The git folder is left alone, in any spelling of its name
+ * (`shared/git-internals.ts`) — a sweep is not a way into it. Used after a recursive folder delete to
+ * sweep the leftover empty-folder shells off disk so the file tree (which
+ * lists on-disk directories, not just tracked files) stops showing the
+ * deleted container. Only a directory that vanished or filled up under a
+ * concurrent writer is passed over; any other failure (permissions, I/O) is
+ * thrown, so a caller never reports a folder gone that is still there.
+ */
+export async function removeEmptyDirs(absoluteDir: string): Promise<void> {
+  // The root itself is judged as it is on disk, a link as a link: `readdir`
+  // would follow a directory link and the sweep would then empty folders
+  // wherever it points — outside the workspace, for a link committed to the
+  // repository. A link is never swept; the children below are `Dirent`s,
+  // for which `isDirectory()` is already false on a link.
+  let root: import('node:fs').Stats;
+  try {
+    root = await fs.lstat(absoluteDir);
+  } catch (err) {
+    if (isGone(err)) return;
+    throw err;
+  }
+  if (!root.isDirectory()) return;
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+  } catch (err) {
+    if (isGone(err)) return;
+    throw err;
+  }
+  // The same folder still, after the listing: a link swapped in between the
+  // `lstat` above and the `readdir` would have had the listing follow it.
+  // Node has no way to list without following on every platform this runs
+  // on, so the identity is checked on both sides of the read instead, and a
+  // folder that changed underneath is left alone — the sweep is hygiene, and
+  // a folder it does not sweep is only a folder that stays listed.
+  const after = await fs.lstat(absoluteDir).catch((err: unknown) => {
+    if (isGone(err)) return null;
+    throw err;
+  });
+  if (!after || !after.isDirectory() || after.ino !== root.ino || after.dev !== root.dev) return;
+  for (const entry of entries) {
+    if (hasGitInternalsSegment(entry.name)) continue;
+    if (entry.isDirectory()) {
+      await removeEmptyDirs(path.join(absoluteDir, entry.name));
+    }
+  }
+  // Re-read after pruning children: a subdir we just emptied now lets this
+  // dir become removable too. Any surviving file (or `.git`) keeps it.
+  let remaining: string[];
+  try {
+    remaining = await fs.readdir(absoluteDir);
+  } catch (err) {
+    if (isGone(err)) return;
+    throw err;
+  }
+  if (remaining.length > 0) return;
+  try {
+    await fs.rmdir(absoluteDir);
+  } catch (err) {
+    // A concurrent writer removed it, or dropped an entry in after the scan:
+    // either way the directory's fate is no longer ours to decide.
+    if (isGone(err) || codeOf(err) === 'ENOTEMPTY' || codeOf(err) === 'EEXIST') return;
+    throw err;
+  }
+}

package/src/modules/workspace/file-readers/README.md

@@ -0,0 +1,32 @@
+# File readers
+
+`read_file` and `grep` dispatch through `FileReaderRegistry`; each document
+format pairs one pure extract function (`extract-*.ts`) with the shared
+content-hash extraction cache (`DocExtractService`). An extraction is returned
+under an `[extracted text of …]` marker whose summary states what was left out.
+
+When an extractor's OUTPUT changes, bump `EXTRACTION_SCHEMA` in
+`doc-extract.service.ts` so cached extractions of unchanged bytes refresh.
+
+## Word (`.docx`)
+
+- Paragraphs become lines; table rows become lines of tab-separated cells.
+- Runs inside a paragraph join with NO separator — Word splits runs mid-word on
+  formatting boundaries.
+- A soft line break (`<w:br/>`, `<w:cr/>`) becomes one space and a tab element
+  (`<w:tab/>`) one tab, between the surrounding run text. Tab STOPS in paragraph
+  properties and breaks inside tracked deletions add nothing.
+- Body only: headers and footers are skipped.
+
+## Known limitations
+
+These are accepted limitations of the document parsers, deliberately left as
+they are:
+
+- **PDF ligatures split words.** The PDF reader joins every text item on a
+  visual line with one space. When pdf.js emits a ligature glyph (`fi`, `fl`, …)
+  as its own item, a space lands inside the word ("fi le"). Merging items by
+  position would also merge real words, so it is not attempted.
+- **Headings are not marked.** Word heading styles (and paragraph styles in
+  general) are not read: a heading extracts as a plain line. The marker summary
+  says formatting is omitted.

package/src/modules/workspace/file-readers/__tests__/doc-extract.test.ts

@@ -1,6 +1,8 @@
+import { readFileSync } from 'node:fs';
 import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import AdmZip from 'adm-zip';
 import * as XLSX from 'xlsx';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -26,7 +28,9 @@ import { notesTargetFromRels } from '../extract-pptx.js';
 
 // ── fixture builders ───────────────────────────────────────────────────────
 
-const W_NS = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"';
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+
+const W_NS ='xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"';
 const A_NS = 'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"';
 
 function docxBytes(bodyXml: string): Buffer {
@@ -195,6 +199,48 @@ describe('extractDocx', () => {
     expect(res.summary).toContain('1 table');
   });
 
+  // Fixture Word files (under ./fixtures) — the reported case: "however", a
+  // soft line break, "suits" came out as "howeversuits".
+  it('turns a soft line break inside a paragraph into one space (fixture)', () => {
+    const res = extractDocx(readFileSync(join(FIXTURES, 'soft-break.docx')));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text).toBe('The terms apply, however suits are filed separately.');
+    expect(res.summary).toContain('formatting omitted');
+  });
+
+  it('turns a tab element into one tab, ignoring tab STOPS in paragraph properties (fixture)', () => {
+    const res = extractDocx(readFileSync(join(FIXTURES, 'tab.docx')));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text).toBe('Name\tValue');
+  });
+
+  it('places breaks between the surrounding run text and still joins other runs with no separator', () => {
+    const p =
+      '<w:p><w:r><w:t>how</w:t></w:r><w:r><w:t>ever</w:t><w:br/><w:t>suits</w:t></w:r>' +
+      '<w:r><w:cr/><w:t>next</w:t><w:tab/><w:t>col</w:t></w:r></w:p>';
+    const res = extractDocx(docxBytes(p));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text).toBe('however suits next\tcol');
+  });
+
+  it('adds nothing for run properties or breaks inside a tracked deletion', () => {
+    const p =
+      '<w:p><w:pPr><w:tabs><w:tab w:val="left" w:pos="720"/></w:tabs></w:pPr>' +
+      '<w:r><w:rPr><w:b/></w:rPr><w:t>kept</w:t></w:r>' +
+      '<w:del w:id="1" w:author="a"><w:r><w:br/><w:delText>gone</w:delText></w:r></w:del>' +
+      '<w:r><w:t>together</w:t></w:r></w:p>';
+    const res = extractDocx(docxBytes(p));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text).toBe('kepttogether');
+  });
+
+  it('keeps a table cell’s soft break as a space, so the row stays one line', () => {
+    const table = `<w:tbl><w:tr><w:tc><w:p><w:r><w:t>a</w:t><w:br/><w:t>b</w:t></w:r></w:p></w:tc><w:tc>${para('c')}</w:tc></w:tr></w:tbl>`;
+    const res = extractDocx(docxBytes(table));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text).toBe('a b\tc');
+  });
+
   it('returns a typed failure for bytes that are not a zip', () => {
     const res = extractDocx(Buffer.from('this is not a docx at all'));
     expect(res.ok).toBe(false);
@@ -215,6 +261,17 @@ describe('extractDocx', () => {
 // ── pptx ───────────────────────────────────────────────────────────────────
 
 describe('extractPptx', () => {
+  it('turns a line break between runs into one space, ignoring tab stops in paragraph properties', () => {
+    const slide =
+      `<?xml version="1.0"?><p:sld xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" ${A_NS}><p:txBody>` +
+      '<a:p><a:pPr><a:tabLst><a:tab pos="914400" algn="l"/></a:tabLst></a:pPr>' +
+      '<a:r><a:t>however</a:t></a:r><a:br><a:rPr lang="en-US"/></a:br><a:r><a:t>suits</a:t></a:r></a:p>' +
+      '</p:txBody></p:sld>';
+    const res = extractPptx(pptxBytes({ 1: slide }));
+    if (!res.ok) throw new Error(res.message);
+    expect(res.text.split('\n')).toEqual(['[slide 1]', 'however suits']);
+  });
+
   it('emits [slide N] markers in NUMERIC order with per-paragraph lines and notes', () => {
     const res = extractPptx(
       pptxBytes(

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

@@ -7,7 +7,10 @@ import { EmailReader } from '../email-reader.js';
 import { FileReaderRegistry, type FileReader, type ReadResult } from '../file-reader.js';
 import { createFileReaderRegistry } from '../file-reader.registry.js';
 import { ImageReader } from '../image-reader.js';
-import { LegacyOfficeReader, TextReader } from '../text-reader.js';
+import { BinaryReader, LegacyOfficeReader, TextReader } from '../text-reader.js';
+import { OCTET_STREAM_FALLBACK_NOTE, contentModeOf, fileTypeOf, needsContent } from '../content-mode.js';
+import { FRONTMATTER_CARRIER_EXTENSIONS, canCarryFrontmatter } from '@bevel-software/platform-shared';
+import { accessFrontmatterExtensionList } from '../../../access-model/access-grammar.js';
 
 /**
  * Routing tests for THE file-reader registry: one lookup (`readerFor`) decides
@@ -56,6 +59,9 @@ describe('file-reader registry routing', () => {
       const reader = registry.readerFor(p);
       expect(reader, p).toBeInstanceOf(ImageReader);
       expect(reader.greppableText, p).toBeUndefined();
+      // A picture is bytes: the text tools refuse it by name.
+      expect(reader.textEditable, p).toBe(false);
+      expect(reader.fileKind, p).toBe('image');
     }
     for (const p of ['a.doc', 'b.ppt', 'c.xls']) {
       const reader = registry.readerFor(p);
@@ -69,13 +75,93 @@ describe('file-reader registry routing', () => {
   });
 
   it('falls back to the plain TextReader for unknown extensions, no extension and dot-files', () => {
-    // `.svg` is markup and `.zip`/`.mp3` are binary-notice cases — all the
-    // text reader's business; `.docx` as a bare dot-file has no extension.
-    for (const p of ['notes.md', 'icon.svg', 'bundle.zip', 'song.mp3', 'noext', 'dir/.gitignore', '.docx']) {
+    // `.svg` is markup — the text reader's business; `.docx` as a bare
+    // dot-file has no extension.
+    for (const p of ['notes.md', 'icon.svg', 'noext', 'dir/.gitignore', '.docx']) {
       const reader = registry.readerFor(p);
       expect(reader, p).toBeInstanceOf(TextReader);
       expect(reader, p).not.toBeInstanceOf(LegacyOfficeReader);
+      expect(reader, p).not.toBeInstanceOf(BinaryReader);
       expect(reader.textEditable, p).toBe(true);
+      expect(reader.fileKind, p).toBe('text');
+    }
+  });
+
+  it('routes archives and media to a BinaryReader: read like the text reader, never text-editable', () => {
+    for (const [p, kind] of [['bundle.zip', 'archive'], ['a/b.tar', 'archive'], ['song.mp3', 'binary'], ['font.woff2', 'binary'], ['fav.ico', 'image']] as const) {
+      const reader = registry.readerFor(p);
+      expect(reader, p).toBeInstanceOf(BinaryReader);
+      expect(reader.textEditable, p).toBe(false);
+      expect(reader.fileKind, p).toBe(kind);
+    }
+  });
+
+  it('fileTypeOf gives the four kinds, a mime and its source from the reader that owns the file', () => {
+    const text = Buffer.from('hello text\n');
+    const bytes = Buffer.from([0x00, 0x01, 0xff]);
+    const typeOf = (p: string, b: Buffer) => {
+      const reader = registry.readerFor(p);
+      return fileTypeOf(reader, p, needsContent(reader) ? b : undefined);
+    };
+    // Extensionless UTF-8: text, as read_file and grep treat it.
+    expect(typeOf('Sample file', text)).toEqual({ contentMode: 'text', kind: 'text', mime: 'text/plain', mimeSource: 'sniff', textEditable: true });
+    expect(typeOf('notes.md', text)).toMatchObject({ kind: 'text', mime: 'text/plain', textEditable: true });
+    // Documents answer from the extension; the content is not consulted.
+    expect(typeOf('plata.pdf', text)).toEqual({ contentMode: 'document', kind: 'document', mime: 'application/pdf', mimeSource: 'extension', textEditable: false });
+    expect(typeOf('memo.docx', bytes)).toMatchObject({
+      kind: 'document',
+      mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+      mimeSource: 'extension',
+      textEditable: false,
+    });
+    expect(typeOf('old.doc', bytes)).toMatchObject({ kind: 'document', mime: 'application/msword', textEditable: false });
+    expect(typeOf('logo.png', bytes)).toEqual({ contentMode: 'binary', kind: 'image', mime: 'image/png', mimeSource: 'extension', textEditable: false });
+    expect(typeOf('scan.tiff', bytes)).toMatchObject({ kind: 'image', textEditable: false });
+    expect(typeOf('bundle.zip', bytes)).toMatchObject({ kind: 'binary', mime: 'application/zip', mimeSource: 'extension' });
+    // Real binary bytes, no known extension: octet-stream, flagged as a fallback.
+    for (const p of ['Sample blob', 'blob.dat']) {
+      expect(typeOf(p, bytes), p).toEqual({
+        contentMode: 'binary',
+        kind: 'binary',
+        mime: 'application/octet-stream',
+        mimeSource: 'fallback',
+        textEditable: false,
+        mimeNote: OCTET_STREAM_FALLBACK_NOTE,
+      });
+    }
+    // Invalid UTF-8 without a NUL is binary too — the write gate would refuse it.
+    expect(typeOf('latin1', Buffer.from([0x63, 0x61, 0x66, 0xe9]))).toMatchObject({ kind: 'binary', mimeSource: 'fallback' });
+    // A named mime never carries the fallback note.
+    expect(typeOf('logo.png', bytes)).not.toHaveProperty('mimeNote');
+  });
+
+  it('every extension a reader claims names its mime — only the fallback reader falls back to octet-stream', () => {
+    const owned = registry.ownedExtensions();
+    expect(owned).toEqual(expect.arrayContaining(['.pdf', '.png', '.doc', '.tiff', '.tgz', '.ogg']));
+    for (const ext of owned) {
+      const p = `file${ext}`;
+      const reader = registry.readerFor(p);
+      const type = fileTypeOf(reader, p, needsContent(reader) ? Buffer.from([0x00, 0xff]) : undefined);
+      expect(type.mimeSource, ext).toBe('extension');
+      expect(type, ext).not.toHaveProperty('mimeNote');
+    }
+    expect(fileTypeOf(registry.readerFor('scan.tiff'), 'scan.tiff', undefined)).toMatchObject({ kind: 'image', mime: 'image/tiff' });
+    expect(fileTypeOf(registry.readerFor('a.tgz'), 'a.tgz', undefined)).toMatchObject({ kind: 'binary', mime: 'application/gzip' });
+    expect(fileTypeOf(registry.readerFor('song.ogg'), 'song.ogg', undefined)).toMatchObject({ kind: 'binary', mime: 'audio/ogg' });
+  });
+
+  it('contentModeOf answers text | document | binary from the same registry the write gates use', () => {
+    const text = Buffer.from('# hello\n');
+    const bytes = Buffer.from([0x00, 0x01, 0xff]);
+    expect(contentModeOf(registry.readerFor('notes.md'), text)).toBe('text');
+    expect(contentModeOf(registry.readerFor('notes.md'), undefined)).toBe('text');
+    // Binary content under a text name is binary: the write gate refuses it.
+    expect(contentModeOf(registry.readerFor('blob.dat'), bytes)).toBe('binary');
+    for (const p of ['deck.pptx', 'report.pdf', 'Inbox/offer.eml']) {
+      expect(contentModeOf(registry.readerFor(p), bytes), p).toBe('document');
+    }
+    for (const p of ['logo.png', 'bundle.zip', 'old.doc', 'song.mp3']) {
+      expect(contentModeOf(registry.readerFor(p), text), p).toBe('binary');
     }
   });
 
@@ -83,6 +169,7 @@ describe('file-reader registry routing', () => {
     const fake: FileReader = {
       extensions: ['.foo'],
       textEditable: false,
+      fileKind: 'binary',
       read: async (): Promise<ReadResult> => ({ kind: 'text', text: 'from the fake reader' }),
     };
     const custom = new FileReaderRegistry([fake, new ImageReader()], new TextReader());
@@ -95,3 +182,45 @@ describe('file-reader registry routing', () => {
     expect(custom.readerFor('x.md')).toBeInstanceOf(TextReader);
   });
 });
+
+/**
+ * `canCarryFrontmatter` (platform-shared) is the one predicate that decides
+ * which files may hold their own access rules; it is derived from this
+ * registry. Pinned here so the two cannot drift: a carrier extension must be
+ * served by a text-editable text reader, and no extension a non-text reader
+ * claims may ever count as a carrier.
+ */
+describe('frontmatter carriers follow the registry', () => {
+  it('the carriers are exactly the resolver’s core access-frontmatter set', () => {
+    // Pinned exactly, so an emptied or widened list fails here rather than
+    // letting the loop below pass vacuously. `accessFrontmatterExtensionList`
+    // may hold overlay registrations from other suites; core's are a subset.
+    expect([...FRONTMATTER_CARRIER_EXTENSIONS].sort()).toEqual(['.md', '.tool']);
+    for (const ext of FRONTMATTER_CARRIER_EXTENSIONS) {
+      expect(accessFrontmatterExtensionList(), ext).toContain(ext);
+    }
+  });
+
+  it('every carrier extension is claimed by no specialised reader and reads as editable text', () => {
+    const owned = new Set(registry.ownedExtensions());
+    expect(FRONTMATTER_CARRIER_EXTENSIONS.length).toBeGreaterThan(0);
+    for (const ext of FRONTMATTER_CARRIER_EXTENSIONS) {
+      expect(owned.has(ext), ext).toBe(false);
+      const reader = registry.readerFor(`Notes/note${ext}`);
+      expect(reader.textEditable, ext).toBe(true);
+      expect(reader.fileKind, ext).toBe('text');
+      expect(canCarryFrontmatter(`Notes/note${ext}`), ext).toBe(true);
+      // Case-sensitive, as the resolver is: `NOTE.MD` carries no enforced rule.
+      expect(canCarryFrontmatter(`Notes/NOTE${ext.toUpperCase()}`), ext).toBe(false);
+    }
+  });
+
+  it('no extension a reader claims is a carrier, and neither is an extensionless file', () => {
+    for (const ext of registry.ownedExtensions()) {
+      expect(canCarryFrontmatter(`Sales/file${ext}`), ext).toBe(false);
+    }
+    for (const p of ['Sales/Report.pdf', 'Sales/Deck.pptx', 'Sales/Logo.png', 'Sales/blob', 'Sales/.hidden', 'notes.txt']) {
+      expect(canCarryFrontmatter(p), p).toBe(false);
+    }
+  });
+});

package/src/modules/workspace/file-readers/content-mode.ts

@@ -0,0 +1,87 @@
+import { DocumentReader } from './document-reader.js';
+import type { FileReader } from './file-reader.js';
+import { isTextBytes } from './text-reader.js';
+
+/**
+ * What the file tools can do with a file's content — the answer `file_stat`
+ * reports so an agent can decide BEFORE acting:
+ *  - `text`: read_file returns it, and write_file/write_files/edit_file accept it;
+ *  - `document`: read_file returns an EXTRACTION; the text tools refuse it;
+ *  - `binary`: bytes only — copy_file/move_file/delete_file/unzip act on it,
+ *    upload replaces it, and the text tools refuse it.
+ */
+export type ContentMode = 'text' | 'document' | 'binary';
+
+/**
+ * The content mode of a file read by `reader`. `bytes` is the file's current
+ * content, consulted only when the reader's answer depends on it (a text-
+ * editable reader holding binary content is `binary`); pass undefined when
+ * there is nothing there yet.
+ */
+export function contentModeOf(reader: FileReader, bytes: Buffer | undefined): ContentMode {
+  if (reader instanceof DocumentReader) return 'document';
+  if (!reader.textEditable) return 'binary';
+  if (reader.editRefusalForExisting === undefined || bytes === undefined) return 'text';
+  return isTextBytes(bytes) ? 'text' : 'binary';
+}
+
+/**
+ * Does `reader`'s answer depend on the bytes? Only a text-editable reader that
+ * judges existing content (the fallback) does; every other reader answers from
+ * the extension alone, so stat need not read the file.
+ */
+export function needsContent(reader: FileReader): boolean {
+  return reader.textEditable && reader.editRefusalForExisting !== undefined;
+}
+
+/** What a file IS, as `file_stat` reports it. Archives count as `binary`; their `mime` says which. */
+export type StatKind = 'text' | 'document' | 'image' | 'binary';
+
+/**
+ * Where `mime` came from: the reader's extension, a content sniff (text with no
+ * known extension is `text/plain`), or the octet-stream fallback — which names
+ * no type at all.
+ */
+export type MimeSource = 'extension' | 'sniff' | 'fallback';
+
+export interface FileType {
+  contentMode: ContentMode;
+  kind: StatKind;
+  mime: string;
+  mimeSource: MimeSource;
+  /** Would write_file/write_files/edit_file accept this file as it is now? */
+  textEditable: boolean;
+  /** Present only for `mimeSource: 'fallback'`: says the mime is not a detected type. */
+  mimeNote?: string;
+}
+
+export const OCTET_STREAM_FALLBACK_NOTE =
+  '`application/octet-stream` is a fallback, not a detected type: no reader names a MIME type for this extension, and the content is not text.';
+
+/**
+ * `file_stat`'s classification, decided by the SAME reader `read_file`, `grep`
+ * and the write gates dispatch to — there is no second table. `bytes` follows
+ * `contentModeOf`: pass the content when `needsContent(reader)`, so the stat
+ * judges exactly what the read and the write gate judge.
+ */
+export function fileTypeOf(reader: FileReader, path: string, bytes: Buffer | undefined): FileType {
+  const contentMode = contentModeOf(reader, bytes);
+  const kind: StatKind =
+    contentMode === 'text'
+      ? 'text'
+      : reader.fileKind === 'text' || reader.fileKind === 'archive'
+        ? 'binary'
+        : reader.fileKind;
+  const textEditable = contentMode === 'text';
+  const named = reader.mimeFor?.(path);
+  if (named !== undefined) return { contentMode, kind, mime: named, mimeSource: 'extension', textEditable };
+  if (contentMode === 'text') return { contentMode, kind, mime: 'text/plain', mimeSource: 'sniff', textEditable };
+  return {
+    contentMode,
+    kind,
+    mime: 'application/octet-stream',
+    mimeSource: 'fallback',
+    textEditable,
+    mimeNote: OCTET_STREAM_FALLBACK_NOTE,
+  };
+}

package/src/modules/workspace/file-readers/doc-extract.service.ts

@@ -45,8 +45,11 @@ export type DocExtractOutcome =
  * v2: extraction moved from hand-rolled scanning to a real XML/HTML parser,
  * which changed self-closing paragraphs, entity edge cases and recovery from
  * malformed parts.
+ *
+ * v3: Word soft line breaks and tab elements (and PowerPoint `<a:br/>`) now
+ * yield a space / tab instead of fusing the words around them.
  */
-export const EXTRACTION_SCHEMA = 'v2';
+export const EXTRACTION_SCHEMA = 'v3';
 
 export class DocExtractService {
   private readonly cache: DocExtractionCache;

package/src/modules/workspace/file-readers/doc-extract.types.ts

@@ -14,6 +14,8 @@
  * into the cached value would surface the wrong path on the second read.
  */
 
+import { sanitizedPath } from '../../../shared/printable.js';
+
 /** A successful extraction: the marker-summary line + the extracted text. */
 export interface ExtractedDoc {
   /**
@@ -47,12 +49,14 @@ export type ExtractFn = (bytes: Buffer) => ExtractResult | Promise<ExtractResult
  *
  * One line is a promise the rest of the read path keeps: grep counts on the
  * marker occupying exactly one, so read_file and grep agree on line numbers.
- * A path may legally carry a CR or LF, which would forge extra lines and shift
- * every number after it, so those are shown as escapes rather than obeyed.
+ * A path may legally carry a line break — CR, LF, or one of the Unicode
+ * separators — which would forge extra lines and shift every number after
+ * it, so those are shown as escapes rather than obeyed: the one rule every
+ * one-line notice uses (`sanitizedPath`), so a path reads the same in the
+ * marker as in a refusal.
  */
 export function extractionMarker(path: string, summary: string): string {
-  const oneLine = path.replace(/[\r\n]/g, (c) => (c === '\r' ? '\\r' : '\\n'));
-  return `[extracted text of ${oneLine} — ${summary}]`;
+  return `[extracted text of ${sanitizedPath(path)} — ${summary}]`;
 }
 
 /** Lowercased extension of `path` including the dot, or '' when there is none. */

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

@@ -1,6 +1,7 @@
 import type { DocExtractService } from './doc-extract.service.js';
 import type { ExtractFn } from './doc-extract.types.js';
 import { displayPath, oneLine, type FileReader, type ReadResult } from './file-reader.js';
+import { extensionMime } from './text-reader.js';
 
 /**
  * FileReader over one document format: a thin wrapper pairing the format's
@@ -23,6 +24,7 @@ export class DocumentReader implements FileReader {
    * uploading a new version).
    */
   readonly textEditable = false;
+  readonly fileKind = 'document' as const;
 
   constructor(
     extension: string,
@@ -56,6 +58,10 @@ export class DocumentReader implements FileReader {
         };
   }
 
+  mimeFor(path: string): string | undefined {
+    return extensionMime(path);
+  }
+
   /** The cached extraction (marker line included, so grep's line numbers match read_file's), or null when cold. */
   async greppableText(bytes: Buffer, path: string): Promise<string | null> {
     const hit = await this.service.getCached(path, bytes);

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

@@ -10,7 +10,13 @@ import { localBlocks, localElementBlocks, localName, paragraphRunText, zipEntryO
  *
  *  - Paragraphs become lines. `<w:t>` runs are concatenated with NO separator
  *    (Word splits runs mid-word on formatting boundaries).
+ *  - A soft line break (`<w:br/>`, `<w:cr/>`) inside a paragraph becomes one
+ *    space and a `<w:tab/>` one tab, between the runs around it.
  *  - Tables become lines with cell text tab-separated, one line per row.
+ *
+ * Known limitation: heading and other paragraph STYLES are not read, so a
+ * heading extracts as a plain line — the summary says formatting is omitted.
+ * See README.md beside this file.
  */
 export function extractDocx(bytes: Buffer): ExtractResult {
   let xml: string;

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

@@ -12,7 +12,7 @@ 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';
+import { BinaryReader, LegacyOfficeReader, TextReader } from './text-reader.js';
 
 /**
  * THE registry of file readers — the one place that says which reader owns
@@ -39,6 +39,14 @@ export function createFileReaderRegistry(docExtract: DocExtractService): FileRea
       new EmailReader('.msg', extractMsg, docExtract),
       new ImageReader(),
       new LegacyOfficeReader(),
+      // Bytes no text tool may write: the image formats read_file does not
+      // show as pictures, archives, and media/fonts/executables.
+      new BinaryReader(['.bmp', '.ico', '.tif', '.tiff', '.heic', '.avif'], 'image'),
+      new BinaryReader(['.zip', '.gz', '.tgz', '.tar', '.7z', '.rar'], 'archive'),
+      new BinaryReader(
+        ['.mp3', '.wav', '.ogg', '.m4a', '.mp4', '.mov', '.webm', '.woff', '.woff2', '.ttf', '.otf', '.wasm', '.exe', '.dll', '.so', '.bin'],
+        'binary',
+      ),
     ],
     new TextReader(),
   );