vellum 0.0.16 → 0.2.0

package/src/__tests__/assistant-event.test.ts

@@ -0,0 +1,123 @@
+import { describe, test, expect } from 'bun:test';
+import type { AssistantEvent } from '../runtime/assistant-event.js';
+import { formatSseFrame, formatSseHeartbeat } from '../runtime/assistant-event.js';
+
+// ── Type / shape tests ────────────────────────────────────────────────────────
+
+describe('AssistantEvent shape', () => {
+  test('accepts a minimal valid event', () => {
+    const event: AssistantEvent = {
+      id: 'evt_001',
+      assistantId: 'ast_123',
+      emittedAt: '2026-02-18T21:20:00.000Z',
+      message: {
+        type: 'assistant_text_delta',
+        sessionId: 'conv_456',
+        text: 'Working on it...',
+      },
+    };
+
+    expect(event.id).toBe('evt_001');
+    expect(event.assistantId).toBe('ast_123');
+    expect(event.sessionId).toBeUndefined();
+    expect(event.emittedAt).toBe('2026-02-18T21:20:00.000Z');
+    expect(event.message.type).toBe('assistant_text_delta');
+  });
+
+  test('accepts a full event with sessionId', () => {
+    const event: AssistantEvent = {
+      id: 'evt_002',
+      assistantId: 'ast_123',
+      sessionId: 'conv_456',
+      emittedAt: '2026-02-18T21:20:00.000Z',
+      message: {
+        type: 'message_complete',
+        sessionId: 'conv_456',
+      },
+    };
+
+    expect(event.sessionId).toBe('conv_456');
+    expect(event.message.type).toBe('message_complete');
+  });
+});
+
+// ── SSE framing tests ─────────────────────────────────────────────────────────
+
+describe('formatSseFrame', () => {
+  const baseEvent: AssistantEvent = {
+    id: 'evt_003',
+    assistantId: 'ast_abc',
+    sessionId: 'sess_xyz',
+    emittedAt: '2026-02-18T00:00:00.000Z',
+    message: {
+      type: 'assistant_text_delta',
+      sessionId: 'sess_xyz',
+      text: 'hello',
+    },
+  };
+
+  test('produces event, id, and data lines followed by blank line', () => {
+    const frame = formatSseFrame(baseEvent);
+    const lines = frame.split('\n');
+
+    expect(lines[0]).toBe('event: assistant_event');
+    expect(lines[1]).toBe(`id: ${baseEvent.id}`);
+    expect(lines[2]).toStartWith('data: ');
+    // Trailing blank line: frame ends with \n\n, so last two entries are '' ''
+    expect(lines[lines.length - 1]).toBe('');
+    expect(lines[lines.length - 2]).toBe('');
+  });
+
+  test('data line contains valid JSON matching the event', () => {
+    const frame = formatSseFrame(baseEvent);
+    const dataLine = frame.split('\n').find((l) => l.startsWith('data: '))!;
+    const parsed = JSON.parse(dataLine.slice('data: '.length)) as AssistantEvent;
+
+    expect(parsed.id).toBe(baseEvent.id);
+    expect(parsed.assistantId).toBe(baseEvent.assistantId);
+    expect(parsed.sessionId).toBe(baseEvent.sessionId);
+    expect(parsed.emittedAt).toBe(baseEvent.emittedAt);
+    expect(parsed.message.type).toBe('assistant_text_delta');
+  });
+
+  test('id line uses the event id verbatim', () => {
+    const event: AssistantEvent = { ...baseEvent, id: 'unique-evt-id-xyz' };
+    const frame = formatSseFrame(event);
+    expect(frame).toContain('id: unique-evt-id-xyz\n');
+  });
+
+  test('strips newline characters from event.id to prevent SSE frame injection', () => {
+    const event: AssistantEvent = { ...baseEvent, id: 'foo\ndata: {"injected":true}' };
+    const frame = formatSseFrame(event);
+    const lines = frame.split('\n');
+    // id line must not contain the injected payload
+    const idLine = lines.find((l) => l.startsWith('id: '))!;
+    expect(idLine).toBe('id: foodata: {"injected":true}');
+    // only one data line must exist
+    const dataLines = lines.filter((l) => l.startsWith('data: '));
+    expect(dataLines).toHaveLength(1);
+  });
+
+  test('event type field is always "assistant_event"', () => {
+    const frame = formatSseFrame(baseEvent);
+    expect(frame.startsWith('event: assistant_event\n')).toBe(true);
+  });
+
+  test('frame ends with double newline', () => {
+    const frame = formatSseFrame(baseEvent);
+    expect(frame.endsWith('\n\n')).toBe(true);
+  });
+});
+
+// ── Heartbeat tests ───────────────────────────────────────────────────────────
+
+describe('formatSseHeartbeat', () => {
+  test('returns a SSE comment line followed by blank line', () => {
+    const hb = formatSseHeartbeat();
+    expect(hb).toBe(': heartbeat\n\n');
+  });
+
+  test('starts with colon (SSE comment marker)', () => {
+    expect(formatSseHeartbeat().startsWith(':')).toBe(true);
+  });
+});

package/src/__tests__/attachments-store.test.ts

@@ -0,0 +1,547 @@
+import { describe, test, expect, beforeEach, afterAll, mock } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const testDir = mkdtempSync(join(tmpdir(), 'attach-store-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+  getRootDir: () => testDir,
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () => new Proxy({} as Record<string, unknown>, {
+    get: () => () => {},
+  }),
+}));
+
+mock.module('../config/loader.js', () => ({
+  getConfig: () => ({
+    model: 'test',
+    provider: 'test',
+    apiKeys: {},
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0, maxTokensPerSession: 0 },
+  }),
+}));
+
+import { initializeDb, getDb } from '../memory/db.js';
+import {
+  uploadAttachment,
+  deleteAttachment,
+  getAttachmentsByIds,
+  getAttachmentById,
+  linkAttachmentToMessage,
+  getAttachmentsForMessage,
+  getAttachmentsForMessageUnscoped,
+  deleteOrphanAttachments,
+  validateAttachmentUpload,
+  isValidBase64,
+  AttachmentUploadError,
+  MAX_UPLOAD_BYTES,
+} from '../memory/attachments-store.js';
+import { createConversation, addMessage } from '../memory/conversation-store.js';
+
+initializeDb();
+
+afterAll(() => {
+  try { rmSync(testDir, { recursive: true }); } catch { /* best effort */ }
+});
+
+function resetTables() {
+  const db = getDb();
+  db.run('DELETE FROM message_attachments');
+  db.run('DELETE FROM attachments');
+  db.run('DELETE FROM messages');
+  db.run('DELETE FROM conversations');
+}
+
+// ---------------------------------------------------------------------------
+// uploadAttachment
+// ---------------------------------------------------------------------------
+
+describe('uploadAttachment', () => {
+  beforeEach(resetTables);
+
+  test('stores attachment and returns metadata', () => {
+    const stored = uploadAttachment('ast-1', 'chart.png', 'image/png', 'iVBORw0K');
+
+    expect(stored.id).toBeDefined();
+    expect(stored.assistantId).toBe('ast-1');
+    expect(stored.originalFilename).toBe('chart.png');
+    expect(stored.mimeType).toBe('image/png');
+    expect(stored.kind).toBe('image');
+    expect(stored.sizeBytes).toBeGreaterThan(0);
+    expect(stored.createdAt).toBeGreaterThan(0);
+  });
+
+  test('classifies image MIME as image kind', () => {
+    const stored = uploadAttachment('ast-1', 'pic.jpg', 'image/jpeg', 'AAAA');
+    expect(stored.kind).toBe('image');
+  });
+
+  test('classifies non-image MIME as document kind', () => {
+    const stored = uploadAttachment('ast-1', 'doc.pdf', 'application/pdf', 'JVBER');
+    expect(stored.kind).toBe('document');
+  });
+
+  test('generates unique IDs for each upload', () => {
+    const a = uploadAttachment('ast-1', 'a.txt', 'text/plain', 'AA==');
+    const b = uploadAttachment('ast-1', 'b.txt', 'text/plain', 'QQ==');
+    expect(a.id).not.toBe(b.id);
+  });
+
+  test('computes sizeBytes from base64 correctly', () => {
+    // "hello" = "aGVsbG8=" (8 chars, 1 pad → 5 bytes)
+    const stored = uploadAttachment('ast-1', 'hello.txt', 'text/plain', 'aGVsbG8=');
+    expect(stored.sizeBytes).toBe(5);
+  });
+
+  test('deduplicates by content hash within the same assistant', () => {
+    const first = uploadAttachment('ast-1', 'photo.png', 'image/png', 'iVBORw0KGgoAAAANSUh');
+    const second = uploadAttachment('ast-1', 'photo.png', 'image/png', 'iVBORw0KGgoAAAANSUh');
+    expect(second.id).toBe(first.id);
+  });
+
+  test('deduplicates even when filenames differ', () => {
+    const first = uploadAttachment('ast-1', 'original.png', 'image/png', 'DUPECONTENT123');
+    const second = uploadAttachment('ast-1', 'renamed.png', 'image/png', 'DUPECONTENT123');
+    expect(second.id).toBe(first.id);
+  });
+
+  test('does not deduplicate across different assistants', () => {
+    const first = uploadAttachment('ast-1', 'file.txt', 'text/plain', 'CROSSASSISTANT');
+    const second = uploadAttachment('ast-2', 'file.txt', 'text/plain', 'CROSSASSISTANT');
+    expect(second.id).not.toBe(first.id);
+  });
+
+  test('does not deduplicate different content', () => {
+    const first = uploadAttachment('ast-1', 'a.txt', 'text/plain', 'CONTENTA');
+    const second = uploadAttachment('ast-1', 'b.txt', 'text/plain', 'CONTENTB');
+    expect(second.id).not.toBe(first.id);
+  });
+
+  test('rejects payloads exceeding MAX_UPLOAD_BYTES', () => {
+    // Build a base64 string that decodes to just over the limit.
+    // 4 base64 chars → 3 bytes, so we need ceil((MAX_UPLOAD_BYTES+1)/3)*4 chars.
+    const oversizedLength = Math.ceil((MAX_UPLOAD_BYTES + 1) / 3) * 4;
+    const oversizedData = 'A'.repeat(oversizedLength);
+
+    expect(() =>
+      uploadAttachment('ast-1', 'huge.bin', 'application/octet-stream', oversizedData),
+    ).toThrow(AttachmentUploadError);
+  });
+
+  test('rejects invalid base64 data', () => {
+    expect(() =>
+      uploadAttachment('ast-1', 'bad.txt', 'text/plain', '!!!not-base64!!!'),
+    ).toThrow(AttachmentUploadError);
+  });
+
+  test('accepts base64 with non-standard padding/length', () => {
+    // Lenient on length — only character set is validated
+    expect(() =>
+      uploadAttachment('ast-1', 'ok.txt', 'text/plain', 'AAA'),
+    ).not.toThrow();
+  });
+
+  test('accepts payload exactly at MAX_UPLOAD_BYTES', () => {
+    // MAX_UPLOAD_BYTES (20 MB) is divisible by 3, so (MAX/3)*4 base64 chars
+    // decodes to exactly MAX bytes with no padding.
+    const exactLength = (MAX_UPLOAD_BYTES / 3) * 4;
+    const exactData = 'A'.repeat(exactLength);
+
+    expect(() =>
+      uploadAttachment('ast-1', 'exact.bin', 'application/octet-stream', exactData),
+    ).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isValidBase64
+// ---------------------------------------------------------------------------
+
+describe('isValidBase64', () => {
+  test('accepts valid base64 strings', () => {
+    expect(isValidBase64('aGVsbG8=')).toBe(true);     // "hello"
+    expect(isValidBase64('dGVzdA==')).toBe(true);      // "test"
+    expect(isValidBase64('AAAA')).toBe(true);          // no padding
+    expect(isValidBase64('')).toBe(true);              // empty
+  });
+
+  test('accepts strings with non-standard length (lenient)', () => {
+    expect(isValidBase64('AAA')).toBe(true);           // 3 chars, OK
+    expect(isValidBase64('AAAAA')).toBe(true);         // 5 chars, OK
+  });
+
+  test('rejects strings with invalid characters', () => {
+    expect(isValidBase64('!!!!')).toBe(false);
+    expect(isValidBase64('abc@')).toBe(false);
+    expect(isValidBase64('hello world')).toBe(false);  // space
+    expect(isValidBase64('data_here')).toBe(false);    // underscore
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deleteAttachment
+// ---------------------------------------------------------------------------
+
+describe('deleteAttachment', () => {
+  beforeEach(resetTables);
+
+  test('deletes existing attachment and returns deleted', () => {
+    const stored = uploadAttachment('ast-1', 'file.txt', 'text/plain', 'dGVzdA==');
+    const result = deleteAttachment('ast-1', stored.id);
+    expect(result).toBe('deleted');
+
+    const fetched = getAttachmentById('ast-1', stored.id);
+    expect(fetched).toBeNull();
+  });
+
+  test('returns not_found for nonexistent attachment', () => {
+    const result = deleteAttachment('ast-1', 'nonexistent-id');
+    expect(result).toBe('not_found');
+  });
+
+  test('returns not_found when assistantId does not match', () => {
+    const stored = uploadAttachment('ast-owner', 'file.txt', 'text/plain', 'dGVzdA==');
+    const result = deleteAttachment('ast-other', stored.id);
+    expect(result).toBe('not_found');
+
+    // Original still exists
+    const fetched = getAttachmentById('ast-owner', stored.id);
+    expect(fetched).not.toBeNull();
+  });
+
+  test('returns still_referenced when messages reference the attachment', () => {
+    const conv = createConversation();
+    const msg1 = addMessage(conv.id, 'user', 'First upload');
+    const msg2 = addMessage(conv.id, 'user', 'Duplicate upload');
+
+    // Dedup: both uploads return the same attachment row
+    const first = uploadAttachment('ast-1', 'photo.png', 'image/png', 'SHAREDCONTENT1');
+    const second = uploadAttachment('ast-1', 'photo.png', 'image/png', 'SHAREDCONTENT1');
+    expect(second.id).toBe(first.id);
+
+    linkAttachmentToMessage(msg1.id, first.id, 0);
+    linkAttachmentToMessage(msg2.id, second.id, 0);
+
+    // Delete should return still_referenced and NOT remove the attachment row
+    const result = deleteAttachment('ast-1', first.id);
+    expect(result).toBe('still_referenced');
+
+    // Attachment row still exists because messages reference it
+    const fetched = getAttachmentById('ast-1', first.id);
+    expect(fetched).not.toBeNull();
+
+    // Both messages still see the attachment
+    const linked1 = getAttachmentsForMessage(msg1.id, 'ast-1');
+    expect(linked1).toHaveLength(1);
+    const linked2 = getAttachmentsForMessage(msg2.id, 'ast-1');
+    expect(linked2).toHaveLength(1);
+  });
+
+  test('deletes attachment when no messages reference it', () => {
+    const stored = uploadAttachment('ast-1', 'lonely.txt', 'text/plain', 'UNREFERENCED');
+    // No linkAttachmentToMessage call — zero references
+    const result = deleteAttachment('ast-1', stored.id);
+    expect(result).toBe('deleted');
+
+    const fetched = getAttachmentById('ast-1', stored.id);
+    expect(fetched).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAttachmentsByIds
+// ---------------------------------------------------------------------------
+
+describe('getAttachmentsByIds', () => {
+  beforeEach(resetTables);
+
+  test('returns matching attachments with data', () => {
+    const a = uploadAttachment('ast-1', 'a.txt', 'text/plain', 'AAAA');
+    const b = uploadAttachment('ast-1', 'b.txt', 'text/plain', 'BBBB');
+
+    const results = getAttachmentsByIds('ast-1', [a.id, b.id]);
+    expect(results).toHaveLength(2);
+    expect(results[0].dataBase64).toBe('AAAA');
+    expect(results[1].dataBase64).toBe('BBBB');
+  });
+
+  test('returns empty array for empty IDs list', () => {
+    const results = getAttachmentsByIds('ast-1', []);
+    expect(results).toHaveLength(0);
+  });
+
+  test('skips IDs that do not exist', () => {
+    const a = uploadAttachment('ast-1', 'a.txt', 'text/plain', 'AAAA');
+    const results = getAttachmentsByIds('ast-1', [a.id, 'nonexistent']);
+    expect(results).toHaveLength(1);
+  });
+
+  test('enforces assistantId scoping', () => {
+    const a = uploadAttachment('ast-owner', 'a.txt', 'text/plain', 'AAAA');
+    const results = getAttachmentsByIds('ast-other', [a.id]);
+    expect(results).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAttachmentById
+// ---------------------------------------------------------------------------
+
+describe('getAttachmentById', () => {
+  beforeEach(resetTables);
+
+  test('returns attachment with data when found', () => {
+    const stored = uploadAttachment('ast-1', 'report.pdf', 'application/pdf', 'JVBER');
+    const result = getAttachmentById('ast-1', stored.id);
+
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe(stored.id);
+    expect(result!.originalFilename).toBe('report.pdf');
+    expect(result!.dataBase64).toBe('JVBER');
+  });
+
+  test('returns null for wrong assistantId', () => {
+    const stored = uploadAttachment('ast-1', 'file.txt', 'text/plain', 'dGVzdA==');
+    const result = getAttachmentById('ast-other', stored.id);
+    expect(result).toBeNull();
+  });
+
+  test('returns null for nonexistent ID', () => {
+    const result = getAttachmentById('ast-1', 'no-such-id');
+    expect(result).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// linkAttachmentToMessage + getAttachmentsForMessage
+// ---------------------------------------------------------------------------
+
+describe('linkAttachmentToMessage + getAttachmentsForMessage', () => {
+  beforeEach(resetTables);
+
+  test('links attachment and retrieves it by message', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Here is a chart');
+    const stored = uploadAttachment('ast-1', 'chart.png', 'image/png', 'iVBORw0K');
+
+    linkAttachmentToMessage(msg.id, stored.id, 0);
+
+    const linked = getAttachmentsForMessage(msg.id, 'ast-1');
+    expect(linked).toHaveLength(1);
+    expect(linked[0].id).toBe(stored.id);
+    expect(linked[0].originalFilename).toBe('chart.png');
+    expect(linked[0].dataBase64).toBe('iVBORw0K');
+  });
+
+  test('returns attachments in position order', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Multiple files');
+    const a = uploadAttachment('ast-1', 'first.txt', 'text/plain', 'AAAA');
+    const b = uploadAttachment('ast-1', 'second.txt', 'text/plain', 'BBBB');
+
+    // Link in reverse order
+    linkAttachmentToMessage(msg.id, b.id, 1);
+    linkAttachmentToMessage(msg.id, a.id, 0);
+
+    const linked = getAttachmentsForMessage(msg.id, 'ast-1');
+    expect(linked).toHaveLength(2);
+    expect(linked[0].originalFilename).toBe('first.txt');
+    expect(linked[1].originalFilename).toBe('second.txt');
+  });
+
+  test('returns empty for message with no attachments', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'No attachments');
+
+    const linked = getAttachmentsForMessage(msg.id, 'ast-1');
+    expect(linked).toHaveLength(0);
+  });
+
+  test('enforces assistantId scoping on retrieval', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Scoped');
+    const stored = uploadAttachment('ast-owner', 'secret.txt', 'text/plain', 'c2VjcmV0');
+
+    linkAttachmentToMessage(msg.id, stored.id, 0);
+
+    const wrongScope = getAttachmentsForMessage(msg.id, 'ast-other');
+    expect(wrongScope).toHaveLength(0);
+
+    const rightScope = getAttachmentsForMessage(msg.id, 'ast-owner');
+    expect(rightScope).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getAttachmentsForMessageUnscoped
+// ---------------------------------------------------------------------------
+
+describe('getAttachmentsForMessageUnscoped', () => {
+  beforeEach(resetTables);
+
+  test('returns attachments without assistant scoping', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Desktop history');
+    const stored = uploadAttachment('ast-1', 'result.png', 'image/png', 'iVBORw0K');
+
+    linkAttachmentToMessage(msg.id, stored.id, 0);
+
+    const linked = getAttachmentsForMessageUnscoped(msg.id);
+    expect(linked).toHaveLength(1);
+    expect(linked[0].id).toBe(stored.id);
+  });
+
+  test('returns empty for message with no links', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Nothing here');
+
+    const linked = getAttachmentsForMessageUnscoped(msg.id);
+    expect(linked).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deleteOrphanAttachments
+// ---------------------------------------------------------------------------
+
+describe('deleteOrphanAttachments', () => {
+  beforeEach(resetTables);
+
+  test('removes candidate attachments with no message links', () => {
+    const stored = uploadAttachment('ast-1', 'orphan.txt', 'text/plain', 'ZGF0YQ==');
+
+    const removed = deleteOrphanAttachments([stored.id]);
+    expect(removed).toBe(1);
+  });
+
+  test('preserves attachments that are still linked', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'With attachment');
+    const stored = uploadAttachment('ast-1', 'linked.txt', 'text/plain', 'ZGF0YQ==');
+    linkAttachmentToMessage(msg.id, stored.id, 0);
+
+    const removed = deleteOrphanAttachments([stored.id]);
+    expect(removed).toBe(0);
+
+    const fetched = getAttachmentById('ast-1', stored.id);
+    expect(fetched).not.toBeNull();
+  });
+
+  test('removes only orphans when mixed candidates provided', () => {
+    const conv = createConversation();
+    const msg = addMessage(conv.id, 'assistant', 'Mixed');
+    const linked = uploadAttachment('ast-1', 'linked.txt', 'text/plain', 'AAAA');
+    const orphan = uploadAttachment('ast-1', 'orphan.txt', 'text/plain', 'BBBB');
+    linkAttachmentToMessage(msg.id, linked.id, 0);
+
+    const removed = deleteOrphanAttachments([linked.id, orphan.id]);
+    expect(removed).toBe(1);
+
+    const remaining = getAttachmentById('ast-1', linked.id);
+    expect(remaining).not.toBeNull();
+  });
+
+  test('returns 0 when no candidates provided', () => {
+    const removed = deleteOrphanAttachments([]);
+    expect(removed).toBe(0);
+  });
+
+  test('does not delete attachments outside the candidate set', () => {
+    const unrelated = uploadAttachment('ast-1', 'unrelated.txt', 'text/plain', 'AAAA');
+    const candidate = uploadAttachment('ast-1', 'candidate.txt', 'text/plain', 'BBBB');
+
+    const removed = deleteOrphanAttachments([candidate.id]);
+    expect(removed).toBe(1);
+
+    // The unrelated attachment should still exist
+    const fetched = getAttachmentById('ast-1', unrelated.id);
+    expect(fetched).not.toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateAttachmentUpload
+// ---------------------------------------------------------------------------
+
+describe('validateAttachmentUpload', () => {
+  test('accepts common image MIME types', () => {
+    expect(validateAttachmentUpload('photo.png', 'image/png').ok).toBe(true);
+    expect(validateAttachmentUpload('pic.jpg', 'image/jpeg').ok).toBe(true);
+    expect(validateAttachmentUpload('anim.gif', 'image/gif').ok).toBe(true);
+    expect(validateAttachmentUpload('sticker.webp', 'image/webp').ok).toBe(true);
+  });
+
+  test('accepts document MIME types', () => {
+    expect(validateAttachmentUpload('doc.pdf', 'application/pdf').ok).toBe(true);
+    expect(validateAttachmentUpload('notes.txt', 'text/plain').ok).toBe(true);
+    expect(validateAttachmentUpload('data.csv', 'text/csv').ok).toBe(true);
+    expect(validateAttachmentUpload('config.json', 'application/json').ok).toBe(true);
+  });
+
+  test('accepts audio and video MIME types', () => {
+    expect(validateAttachmentUpload('voice.ogg', 'audio/ogg').ok).toBe(true);
+    expect(validateAttachmentUpload('song.mp3', 'audio/mpeg').ok).toBe(true);
+    expect(validateAttachmentUpload('clip.mp4', 'video/mp4').ok).toBe(true);
+  });
+
+  test('accepts application/octet-stream fallback', () => {
+    expect(validateAttachmentUpload('data.bin', 'application/octet-stream').ok).toBe(true);
+  });
+
+  test('rejects dangerous file extensions', () => {
+    const exeResult = validateAttachmentUpload('malware.exe', 'application/octet-stream');
+    expect(exeResult.ok).toBe(false);
+    if (!exeResult.ok) expect(exeResult.error).toContain('.exe');
+
+    const shResult = validateAttachmentUpload('script.sh', 'text/plain');
+    expect(shResult.ok).toBe(false);
+    if (!shResult.ok) expect(shResult.error).toContain('.sh');
+
+    const isoResult = validateAttachmentUpload('disk.iso', 'application/octet-stream');
+    expect(isoResult.ok).toBe(false);
+    if (!isoResult.ok) expect(isoResult.error).toContain('.iso');
+  });
+
+  test('rejects dangerous extensions regardless of claimed MIME type', () => {
+    // .exe disguised as image/png
+    const result = validateAttachmentUpload('payload.exe', 'image/png');
+    expect(result.ok).toBe(false);
+  });
+
+  test('extension check is case-insensitive', () => {
+    expect(validateAttachmentUpload('PROGRAM.EXE', 'application/octet-stream').ok).toBe(false);
+    expect(validateAttachmentUpload('script.SH', 'text/plain').ok).toBe(false);
+  });
+
+  test('rejects unsupported MIME types', () => {
+    const result = validateAttachmentUpload('file.unknown', 'application/x-msdownload');
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain('Unsupported MIME type');
+  });
+
+  test('handles filenames without extensions', () => {
+    // No extension — only MIME check applies
+    expect(validateAttachmentUpload('Makefile', 'text/plain').ok).toBe(true);
+    expect(validateAttachmentUpload('Makefile', 'application/x-evil').ok).toBe(false);
+  });
+
+  test('rejects all dangerous extension variants', () => {
+    for (const ext of ['bat', 'cmd', 'com', 'msi', 'dmg', 'app', 'scr', 'pif', 'vbs', 'ps1', 'jar']) {
+      const result = validateAttachmentUpload(`file.${ext}`, 'application/octet-stream');
+      expect(result.ok).toBe(false);
+    }
+  });
+});