feat(brain): @mosaic/brain structured data service (#11)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/brain/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json tsconfig.json ./
+COPY src/ src/
+# In standalone mode, @mosaic/types is bundled or installed from registry
+RUN npm install && npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/dist/ dist/
+COPY --from=builder /app/node_modules/ node_modules/
+COPY package.json ./
+ENV NODE_ENV=production
+ENV PORT=8100
+ENV MOSAIC_BRAIN_DATA_DIR=/data
+EXPOSE 8100
+VOLUME /data
+CMD ["node", "dist/index.js"]

packages/brain/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mosaic/brain",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mosaic-brain": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo 'ok'",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@mosaic/types": "workspace:*",
+    "fastify": "^5.3.3",
+    "proper-lockfile": "^4.1.2",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/proper-lockfile": "^4",
+    "tsx": "^4",
+    "typescript": "^5",
+    "vitest": "^3"
+  },
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaic/npm",
+    "access": "public"
+  }
+}

packages/brain/src/index.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import Fastify from 'fastify';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { JsonStore } from './storage/json-store.js';
+import { Collections } from './storage/collections.js';
+import { requireAuth } from './middleware/auth.js';
+import { registerRoutes } from './routes/api.js';
+import { registerMcpTools } from './mcp/tools.js';
+
+const HOST = process.env['HOST'] ?? '0.0.0.0';
+const PORT = Number(process.env['PORT'] ?? 8100);
+const DATA_DIR = process.env['MOSAIC_BRAIN_DATA_DIR'] ?? './data';
+
+/**
+ * Create a fresh MCP server instance with all tools registered.
+ * Each HTTP request gets its own instance to avoid state leaks.
+ */
+function createMcpServer(collections: Collections): McpServer {
+  const mcp = new McpServer({
+    name: 'mosaic-brain',
+    version: '0.1.0',
+  });
+  registerMcpTools(mcp, collections);
+  return mcp;
+}
+
+async function main(): Promise<void> {
+  // --- Storage ---
+  const store = new JsonStore({ dataDir: DATA_DIR });
+  await store.init();
+  const collections = new Collections(store);
+
+  // --- Fastify ---
+  const app = Fastify({ logger: true });
+
+  // Auth on all /v1 and /mcp routes
+  app.addHook('onRequest', async (req, reply) => {
+    if (req.url.startsWith('/v1/') || req.url === '/mcp') {
+      await requireAuth(req, reply);
+    }
+  });
+
+  // REST API
+  registerRoutes(app, collections);
+
+  // MCP over HTTP (Streamable HTTP transport)
+  // Each request gets a fresh McpServer + transport to avoid state leaks
+  app.all('/mcp', async (req, reply) => {
+    const mcp = createMcpServer(collections);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined, // stateless
+    });
+    await mcp.connect(transport);
+
+    if (req.method === 'POST') {
+      await transport.handleRequest(
+        req.raw,
+        reply.raw,
+        req.body as Record<string, unknown>,
+      );
+    } else if (req.method === 'GET') {
+      await transport.handleRequest(req.raw, reply.raw);
+    } else if (req.method === 'DELETE') {
+      await transport.handleRequest(req.raw, reply.raw);
+    } else {
+      reply.code(405).send({ error: 'Method not allowed' });
+    }
+  });
+
+  // --- Start ---
+  await app.listen({ host: HOST, port: PORT });
+  console.log(`mosaic-brain listening on ${HOST}:${PORT}`);
+  console.log(`  REST API: http://${HOST}:${PORT}/v1/`);
+  console.log(`  MCP:      http://${HOST}:${PORT}/mcp`);
+  console.log(`  Data dir: ${DATA_DIR}`);
+}
+
+main().catch((err) => {
+  console.error('Failed to start mosaic-brain:', err);
+  process.exit(1);
+});

packages/brain/src/mcp/tools.ts

@@ -0,0 +1,347 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { Collections } from '../storage/collections.js';
+import {
+  BrainTaskSchema, BrainTaskUpdateSchema,
+  BrainProjectSchema, BrainProjectUpdateSchema,
+  BrainEventSchema, BrainEventUpdateSchema,
+  BrainAgentUpdateSchema,
+  BrainMissionSchema, BrainMissionUpdateSchema,
+  BrainMissionTaskSchema, BrainMissionTaskUpdateSchema,
+  BrainDomainSchema, TaskPrioritySchema, BrainTaskStatusSchema,
+  BrainProjectStatusSchema, BrainEventTypeSchema, BrainEventStatusSchema,
+  BrainMissionStatusSchema, BrainAgentStatusSchema,
+} from '../schemas.js';
+
+export function registerMcpTools(mcp: McpServer, collections: Collections): void {
+
+  // === Query Tools ===
+
+  mcp.tool('brain_tasks',
+    'Query tasks with filters. Returns sorted by priority then due date.',
+    {
+      status: BrainTaskStatusSchema.optional(),
+      priority: TaskPrioritySchema.optional(),
+      domain: BrainDomainSchema.optional(),
+      project: z.string().optional(),
+      due_before: z.string().optional(),
+      due_after: z.string().optional(),
+      assignee: z.string().optional(),
+      limit: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      const tasks = await collections.getTasks(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_projects',
+    'Query projects with filters. Returns sorted by priority.',
+    {
+      status: BrainProjectStatusSchema.optional(),
+      domain: BrainDomainSchema.optional(),
+      priority_min: z.number().int().optional(),
+      priority_max: z.number().int().optional(),
+      limit: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      const projects = await collections.getProjects(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(projects, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_events',
+    'Query events with filters. Returns sorted by date then time.',
+    {
+      date_from: z.string().optional(),
+      date_to: z.string().optional(),
+      domain: BrainDomainSchema.optional(),
+      type: BrainEventTypeSchema.optional(),
+      status: BrainEventStatusSchema.optional(),
+      limit: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      const events = await collections.getEvents(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(events, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_agents',
+    'Query active agent sessions.',
+    {
+      status: BrainAgentStatusSchema.optional(),
+      project: z.string().optional(),
+    },
+    async (args) => {
+      const agents = await collections.getAgents(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(agents, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_tickets',
+    'Query helpdesk tickets.',
+    {
+      status: z.number().int().optional(),
+      priority: z.number().int().optional(),
+      limit: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      const tickets = await collections.getTickets(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(tickets, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_today',
+    'Daily summary: events, near-term tasks, stale items, blocked items, active missions, stats.',
+    { date: z.string().optional() },
+    async (args) => {
+      const summary = await collections.getToday(args.date);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(summary, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_stale',
+    'Find tasks and projects not updated in N+ days.',
+    { days: z.number().int().positive().default(7) },
+    async (args) => {
+      const report = await collections.getStale(args.days);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(report, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_stats',
+    'Brain statistics: counts by collection, domain, status.',
+    {},
+    async () => {
+      const stats = await collections.getStats();
+      return { content: [{ type: 'text' as const, text: JSON.stringify(stats, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_search',
+    'Full-text search across titles and notes (deterministic, not semantic).',
+    {
+      query: z.string().min(1),
+      collection: z.enum(['tasks', 'projects', 'events', 'missions']).optional(),
+    },
+    async (args) => {
+      const results = await collections.search(args.query, args.collection);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_audit',
+    'Data integrity check: orphan references, broken dependencies, missing fields, duplicate IDs.',
+    {},
+    async () => {
+      const result = await collections.audit();
+      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+
+  // === Mutation Tools ===
+
+  mcp.tool('brain_add_task',
+    'Create a new task with schema validation.',
+    BrainTaskSchema.shape,
+    async (args) => {
+      try {
+        const task = BrainTaskSchema.parse(args);
+        const result = await collections.addTask(task);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_update_task',
+    'Update an existing task. Auto-sets updated timestamp.',
+    {
+      id: z.string(),
+      ...BrainTaskUpdateSchema.shape,
+    },
+    async ({ id, ...updates }) => {
+      try {
+        const result = await collections.updateTask(id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_add_project',
+    'Create a new project with schema validation.',
+    BrainProjectSchema.shape,
+    async (args) => {
+      try {
+        const project = BrainProjectSchema.parse(args);
+        const result = await collections.addProject(project);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_update_project',
+    'Update an existing project. Auto-sets updated timestamp.',
+    {
+      id: z.string(),
+      ...BrainProjectUpdateSchema.shape,
+    },
+    async ({ id, ...updates }) => {
+      try {
+        const result = await collections.updateProject(id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_add_event',
+    'Create a new event with schema validation.',
+    BrainEventSchema.shape,
+    async (args) => {
+      try {
+        const event = BrainEventSchema.parse(args);
+        const result = await collections.addEvent(event);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_update_event',
+    'Update an existing event.',
+    {
+      id: z.string(),
+      ...BrainEventUpdateSchema.shape,
+    },
+    async ({ id, ...updates }) => {
+      try {
+        const result = await collections.updateEvent(id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_update_agent',
+    'Update an agent session (auto-creates if not found).',
+    {
+      id: z.string(),
+      ...BrainAgentUpdateSchema.shape,
+    },
+    async ({ id, ...updates }) => {
+      try {
+        const result = await collections.updateAgent(id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  // === Mission Tools ===
+
+  mcp.tool('brain_missions',
+    'List and filter missions.',
+    {
+      status: BrainMissionStatusSchema.optional(),
+      project: z.string().optional(),
+      limit: z.number().int().positive().optional(),
+    },
+    async (args) => {
+      const missions = await collections.getMissions(args);
+      return { content: [{ type: 'text' as const, text: JSON.stringify(missions, null, 2) }] };
+    },
+  );
+
+  mcp.tool('brain_mission',
+    'Get, create, or update a single mission. For read: provide id only. For create: provide all required fields. For update: provide id plus fields to change.',
+    {
+      id: z.string(),
+      title: z.string().optional(),
+      project: z.string().optional(),
+      prd_path: z.string().nullish(),
+      status: BrainMissionStatusSchema.optional(),
+      created: z.string().optional(),
+      updated: z.string().optional(),
+      notes: z.string().nullish(),
+      action: z.enum(['get', 'create', 'update']).default('get'),
+    },
+    async (args) => {
+      try {
+        const { action, ...fields } = args;
+        if (action === 'get') {
+          const summary = await collections.getMissionSummary(fields.id);
+          if (!summary) return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Mission not found' }) }], isError: true };
+          return { content: [{ type: 'text' as const, text: JSON.stringify(summary, null, 2) }] };
+        }
+        if (action === 'create') {
+          const mission = BrainMissionSchema.parse(fields);
+          const result = await collections.addMission(mission);
+          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+        }
+        // update
+        const { id, ...updates } = fields;
+        const result = await collections.updateMission(id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+
+  mcp.tool('brain_mission_tasks',
+    'List, create, or update tasks within a mission. For list: provide mission_id. For create: provide all required fields. For update: provide mission_id, id, and fields to change.',
+    {
+      mission_id: z.string(),
+      id: z.string().optional(),
+      title: z.string().optional(),
+      phase: z.string().nullish(),
+      status: BrainTaskStatusSchema.optional(),
+      priority: TaskPrioritySchema.optional(),
+      dependencies: z.array(z.string()).optional(),
+      assigned_to: z.string().nullish(),
+      pr: z.string().nullish(),
+      order: z.number().int().optional(),
+      created: z.string().optional(),
+      updated: z.string().optional(),
+      completed_at: z.string().nullish(),
+      notes: z.string().nullish(),
+      action: z.enum(['list', 'create', 'update']).default('list'),
+    },
+    async (args) => {
+      try {
+        const { action, mission_id, ...fields } = args;
+        if (action === 'list') {
+          const tasks = await collections.getMissionTasks({
+            mission_id,
+            status: fields.status,
+            phase: fields.phase ?? undefined,
+            priority: fields.priority,
+          });
+          return { content: [{ type: 'text' as const, text: JSON.stringify(tasks, null, 2) }] };
+        }
+        if (action === 'create') {
+          const task = BrainMissionTaskSchema.parse({ ...fields, mission_id });
+          const result = await collections.addMissionTask(task);
+          return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+        }
+        // update
+        if (!fields.id) return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'id required for update' }) }], isError: true };
+        const { id, ...updates } = fields;
+        const result = await collections.updateMissionTask(mission_id, id, updates);
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (e: unknown) {
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ error: String(e) }) }], isError: true };
+      }
+    },
+  );
+}

packages/brain/src/middleware/auth.ts

@@ -0,0 +1,25 @@
+import { timingSafeEqual } from 'node:crypto';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+
+const API_KEY = process.env['MOSAIC_BRAIN_API_KEY'] ?? '';
+
+function safeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+export async function requireAuth(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+  if (!API_KEY) return; // No key configured = open access (dev mode)
+
+  const authHeader = request.headers.authorization;
+  if (!authHeader?.startsWith('Bearer ')) {
+    reply.code(401).send({ error: 'Missing or invalid Authorization header', code: 'UNAUTHORIZED' });
+    return reply.hijack();
+  }
+
+  const token = authHeader.slice(7);
+  if (!safeCompare(token, API_KEY)) {
+    reply.code(401).send({ error: 'Invalid API key', code: 'UNAUTHORIZED' });
+    return reply.hijack();
+  }
+}

packages/brain/src/routes/api.ts

@@ -0,0 +1,190 @@
+import type { FastifyInstance } from 'fastify';
+import type { Collections } from '../storage/collections.js';
+import {
+  BrainTaskSchema, BrainTaskUpdateSchema,
+  BrainProjectSchema, BrainProjectUpdateSchema,
+  BrainEventSchema, BrainEventUpdateSchema,
+  BrainAgentUpdateSchema,
+  BrainMissionSchema, BrainMissionUpdateSchema,
+  BrainMissionTaskSchema, BrainMissionTaskUpdateSchema,
+} from '../schemas.js';
+
+function parseFilters(query: Record<string, string | undefined>): Record<string, unknown> {
+  const filters: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) continue;
+    if (key === 'limit' || key === 'priority_min' || key === 'priority_max') {
+      filters[key] = Number(value);
+    } else {
+      filters[key] = value;
+    }
+  }
+  return filters;
+}
+
+export function registerRoutes(app: FastifyInstance, collections: Collections): void {
+
+  // === Health ===
+  app.get('/health', async () => ({ status: 'ok', service: 'mosaic-brain', version: '0.1.0' }));
+
+  // === Tasks ===
+  app.get('/v1/tasks', async (req) => collections.getTasks(parseFilters(req.query as Record<string, string>)));
+  app.get<{ Params: { id: string } }>('/v1/tasks/:id', async (req, reply) => {
+    const task = await collections.getTask(req.params.id);
+    if (!task) return reply.code(404).send({ error: 'Task not found', code: 'NOT_FOUND' });
+    return task;
+  });
+  app.post('/v1/tasks', async (req, reply) => {
+    try {
+      const parsed = BrainTaskSchema.parse(req.body);
+      return await collections.addTask(parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+  app.patch<{ Params: { id: string } }>('/v1/tasks/:id', async (req, reply) => {
+    try {
+      const parsed = BrainTaskUpdateSchema.parse(req.body);
+      return await collections.updateTask(req.params.id, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Projects ===
+  app.get('/v1/projects', async (req) => collections.getProjects(parseFilters(req.query as Record<string, string>)));
+  app.get<{ Params: { id: string } }>('/v1/projects/:id', async (req, reply) => {
+    const project = await collections.getProject(req.params.id);
+    if (!project) return reply.code(404).send({ error: 'Project not found', code: 'NOT_FOUND' });
+    return project;
+  });
+  app.post('/v1/projects', async (req, reply) => {
+    try {
+      const parsed = BrainProjectSchema.parse(req.body);
+      return await collections.addProject(parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+  app.patch<{ Params: { id: string } }>('/v1/projects/:id', async (req, reply) => {
+    try {
+      const parsed = BrainProjectUpdateSchema.parse(req.body);
+      return await collections.updateProject(req.params.id, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Events ===
+  app.get('/v1/events', async (req) => collections.getEvents(parseFilters(req.query as Record<string, string>)));
+  app.get<{ Params: { id: string } }>('/v1/events/:id', async (req, reply) => {
+    const event = await collections.getEvent(req.params.id);
+    if (!event) return reply.code(404).send({ error: 'Event not found', code: 'NOT_FOUND' });
+    return event;
+  });
+  app.post('/v1/events', async (req, reply) => {
+    try {
+      const parsed = BrainEventSchema.parse(req.body);
+      return await collections.addEvent(parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+  app.patch<{ Params: { id: string } }>('/v1/events/:id', async (req, reply) => {
+    try {
+      const parsed = BrainEventUpdateSchema.parse(req.body);
+      return await collections.updateEvent(req.params.id, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Agents ===
+  app.get('/v1/agents', async (req) => collections.getAgents(parseFilters(req.query as Record<string, string>)));
+  app.patch<{ Params: { id: string } }>('/v1/agents/:id', async (req, reply) => {
+    try {
+      const parsed = BrainAgentUpdateSchema.parse(req.body);
+      return await collections.updateAgent(req.params.id, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Tickets ===
+  app.get('/v1/tickets', async (req) => {
+    const q = req.query as Record<string, string>;
+    return collections.getTickets({
+      status: q['status'] ? Number(q['status']) : undefined,
+      priority: q['priority'] ? Number(q['priority']) : undefined,
+      limit: q['limit'] ? Number(q['limit']) : undefined,
+    });
+  });
+
+  // === Missions ===
+  app.get('/v1/missions', async (req) => collections.getMissions(parseFilters(req.query as Record<string, string>)));
+  app.get<{ Params: { id: string } }>('/v1/missions/:id', async (req, reply) => {
+    const summary = await collections.getMissionSummary(req.params.id);
+    if (!summary) return reply.code(404).send({ error: 'Mission not found', code: 'NOT_FOUND' });
+    return summary;
+  });
+  app.post('/v1/missions', async (req, reply) => {
+    try {
+      const parsed = BrainMissionSchema.parse(req.body);
+      return await collections.addMission(parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+  app.patch<{ Params: { id: string } }>('/v1/missions/:id', async (req, reply) => {
+    try {
+      const parsed = BrainMissionUpdateSchema.parse(req.body);
+      return await collections.updateMission(req.params.id, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Mission Tasks ===
+  app.get<{ Params: { id: string } }>('/v1/missions/:id/tasks', async (req) => {
+    const q = req.query as Record<string, string>;
+    return collections.getMissionTasks({
+      mission_id: req.params.id,
+      status: q['status'] as any,
+      phase: q['phase'],
+      priority: q['priority'] as any,
+    });
+  });
+  app.post<{ Params: { id: string } }>('/v1/missions/:id/tasks', async (req, reply) => {
+    try {
+      const parsed = BrainMissionTaskSchema.parse({ ...(req.body as object), mission_id: req.params.id });
+      return await collections.addMissionTask(parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+  app.patch<{ Params: { id: string; taskId: string } }>('/v1/missions/:id/tasks/:taskId', async (req, reply) => {
+    try {
+      const parsed = BrainMissionTaskUpdateSchema.parse(req.body);
+      return await collections.updateMissionTask(req.params.id, req.params.taskId, parsed);
+    } catch (e: unknown) {
+      return reply.code(400).send({ error: String(e), code: 'VALIDATION_ERROR' });
+    }
+  });
+
+  // === Computed Endpoints ===
+  app.get('/v1/today', async (req) => {
+    const q = req.query as Record<string, string>;
+    return collections.getToday(q['date']);
+  });
+  app.get('/v1/stale', async (req) => {
+    const q = req.query as Record<string, string>;
+    return collections.getStale(q['days'] ? Number(q['days']) : undefined);
+  });
+  app.get('/v1/stats', async () => collections.getStats());
+  app.get('/v1/search', async (req) => {
+    const q = req.query as Record<string, string>;
+    if (!q['q']) return [];
+    return collections.search(q['q'], q['collection']);
+  });
+  app.get('/v1/audit', async () => collections.audit());
+}

packages/brain/src/schemas.ts

@@ -0,0 +1,222 @@
+import { z } from 'zod';
+
+// === Enums ===
+
+export const BrainDomainSchema = z.enum([
+  'work', 'software-dev', 'homelab', 'family', 'marriage',
+  'finances', 'fitness', 'music', 'home-improvement', 'woodworking',
+  'home', 'consulting', 'personal',
+]);
+
+export const TaskPrioritySchema = z.enum(['critical', 'high', 'medium', 'low']);
+
+export const BrainTaskStatusSchema = z.enum([
+  'backlog', 'scheduled', 'in-progress', 'blocked', 'done', 'cancelled',
+]);
+
+export const BrainProjectStatusSchema = z.enum([
+  'planning', 'active', 'paused', 'blocked', 'completed', 'archived',
+]);
+
+export const BrainAgentStatusSchema = z.enum(['active', 'idle', 'blocked', 'completed']);
+
+export const BrainEventTypeSchema = z.enum([
+  'meeting', 'deadline', 'maintenance', 'event', 'recurring',
+  'milestone', 'task', 'constraint', 'client-work', 'appointment',
+  'reminder', 'conflict', 'time-off',
+]);
+
+export const BrainEventStatusSchema = z.enum([
+  'scheduled', 'confirmed', 'tentative', 'completed', 'cancelled',
+  'done', 'blocked', 'postponed', 'deferred', 'in-progress',
+  'pending-approval', 'canceled', 'needs-resolution',
+]);
+
+export const BrainMissionStatusSchema = z.enum([
+  'planning', 'active', 'blocked', 'completed', 'cancelled',
+]);
+
+// === Record Schemas ===
+
+export const BrainTaskSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  title: z.string().min(1),
+  domain: BrainDomainSchema,
+  project: z.string().nullish(),
+  priority: TaskPrioritySchema,
+  status: BrainTaskStatusSchema,
+  progress: z.number().int().min(0).max(100).nullish(),
+  due: z.string().nullish(),
+  blocks: z.array(z.string()).optional().default([]),
+  blocked_by: z.array(z.string()).optional().default([]),
+  related: z.array(z.string()).optional().default([]),
+  canonical_source: z.string().nullish(),
+  assignee: z.string().nullish(),
+  created: z.string(),
+  updated: z.string(),
+  notes: z.string().nullish(),
+  notes_nontechnical: z.string().nullish(),
+});
+
+export const BrainProjectSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  name: z.string().min(1),
+  description: z.string().nullish(),
+  domain: BrainDomainSchema,
+  status: BrainProjectStatusSchema,
+  priority: z.number().int().min(1).max(10),
+  progress: z.number().int().min(0).max(100).nullish(),
+  repo: z.string().nullish(),
+  branch: z.string().nullish(),
+  current_milestone: z.string().nullish(),
+  next_milestone: z.string().nullish(),
+  blocker: z.string().nullish(),
+  owner: z.string().nullish(),
+  docs_path: z.string().nullish(),
+  created: z.string(),
+  updated: z.string(),
+  notes: z.string().nullish(),
+  notes_nontechnical: z.string().nullish(),
+});
+
+export const BrainEventSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  title: z.string().min(1),
+  date: z.string(),
+  end_date: z.string().nullish(),
+  time: z.string().nullish(),
+  end_time: z.string().nullish(),
+  domain: BrainDomainSchema,
+  type: BrainEventTypeSchema,
+  status: BrainEventStatusSchema.optional().default('scheduled'),
+  priority: TaskPrioritySchema.nullish(),
+  recur: z.boolean().nullish(),
+  recur_rate: z.string().nullish(),
+  recur_start: z.string().nullish(),
+  recur_end: z.string().nullish(),
+  location: z.string().nullish(),
+  project: z.string().nullish(),
+  related_task: z.string().nullish(),
+  related_tasks: z.array(z.string()).optional().default([]),
+  notes: z.string().nullish(),
+  gcal_id: z.string().nullish(),
+  ics_uid: z.string().nullish(),
+});
+
+export const BrainAgentSchema = z.object({
+  id: z.string(),
+  project: z.string(),
+  focus: z.string().nullish(),
+  repo: z.string().nullish(),
+  branch: z.string().nullish(),
+  status: BrainAgentStatusSchema,
+  workload: z.enum(['light', 'medium', 'heavy']).nullish(),
+  next_step: z.string().nullish(),
+  blocker: z.string().nullish(),
+  updated: z.string(),
+});
+
+export const BrainTicketSchema = z.object({
+  id: z.string(),
+  title: z.string().min(1),
+  status: z.number().int(),
+  priority: z.number().int(),
+  urgency: z.number().int(),
+  impact: z.number().int(),
+  date_creation: z.string(),
+  date_mod: z.string(),
+  content: z.string().nullish(),
+  assigned_to: z.string().nullish(),
+});
+
+export const BrainAppreciationSchema = z.object({
+  date: z.string(),
+  from: z.enum(['jason', 'melanie']),
+  to: z.enum(['jason', 'melanie']),
+  text: z.string().min(1),
+});
+
+export const BrainMissionSchema = z.object({
+  id: z.string(),
+  title: z.string().min(1),
+  project: z.string(),
+  prd_path: z.string().nullish(),
+  status: BrainMissionStatusSchema,
+  created: z.string(),
+  updated: z.string(),
+  notes: z.string().nullish(),
+});
+
+export const BrainMissionTaskSchema = z.object({
+  id: z.string(),
+  mission_id: z.string(),
+  title: z.string().min(1),
+  phase: z.string().nullish(),
+  status: BrainTaskStatusSchema,
+  priority: TaskPrioritySchema,
+  dependencies: z.array(z.string()).default([]),
+  assigned_to: z.string().nullish(),
+  pr: z.string().nullish(),
+  order: z.number().int(),
+  created: z.string(),
+  updated: z.string(),
+  completed_at: z.string().nullish(),
+  notes: z.string().nullish(),
+});
+
+// === Partial schemas for updates ===
+
+export const BrainTaskUpdateSchema = BrainTaskSchema.partial().omit({ id: true });
+export const BrainProjectUpdateSchema = BrainProjectSchema.partial().omit({ id: true });
+export const BrainEventUpdateSchema = BrainEventSchema.partial().omit({ id: true });
+export const BrainAgentUpdateSchema = BrainAgentSchema.partial().omit({ id: true });
+export const BrainMissionUpdateSchema = BrainMissionSchema.partial().omit({ id: true });
+export const BrainMissionTaskUpdateSchema = BrainMissionTaskSchema.partial().omit({ id: true, mission_id: true });
+
+// === Collection file schemas ===
+
+export const TasksFileSchema = z.object({
+  version: z.string(),
+  tasks: z.array(BrainTaskSchema),
+});
+
+export const ProjectsFileSchema = z.object({
+  version: z.string(),
+  projects: z.array(BrainProjectSchema),
+});
+
+export const EventsFileSchema = z.object({
+  version: z.string(),
+  domain: BrainDomainSchema,
+  events: z.array(BrainEventSchema),
+  overdue: z.array(z.object({
+    id: z.string(),
+    title: z.string(),
+    original_due: z.string().optional(),
+    domain: z.string(),
+    notes: z.string().nullish(),
+  })).default([]),
+});
+
+export const AgentsFileSchema = z.object({
+  version: z.string(),
+  agents: z.array(BrainAgentSchema),
+});
+
+export const MissionsFileSchema = z.object({
+  version: z.string(),
+  missions: z.array(BrainMissionSchema),
+});
+
+export const MissionTasksFileSchema = z.object({
+  version: z.string(),
+  mission_tasks: z.array(BrainMissionTaskSchema),
+});
+
+// Inferred types for convenience
+export type BrainTaskInput = z.input<typeof BrainTaskSchema>;
+export type BrainProjectInput = z.input<typeof BrainProjectSchema>;
+export type BrainEventInput = z.input<typeof BrainEventSchema>;
+export type BrainAgentInput = z.input<typeof BrainAgentSchema>;
+export type BrainMissionInput = z.input<typeof BrainMissionSchema>;
+export type BrainMissionTaskInput = z.input<typeof BrainMissionTaskSchema>;

packages/brain/src/storage/collections.ts

@@ -0,0 +1,536 @@
+import type {
+  BrainTask, BrainProject, BrainEvent, BrainAgent,
+  BrainTicket, BrainAppreciation, BrainMission, BrainMissionTask,
+  BrainTaskFilters, BrainProjectFilters, BrainEventFilters,
+  BrainMissionFilters, BrainMissionTaskFilters,
+  BrainMissionSummary, BrainTodaySummary, BrainStats,
+  BrainStaleReport, BrainAuditResult, BrainSearchResult,
+  TaskPriority,
+} from '@mosaic/types';
+import { JsonStore } from './json-store.js';
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+interface TasksFile { version: string; tasks: BrainTask[] }
+interface ProjectsFile { version: string; projects: BrainProject[] }
+interface EventsFile { version: string; events: BrainEvent[] }
+interface AgentsFile { version: string; agents: BrainAgent[] }
+interface TicketsFile { version: string; tickets: BrainTicket[] }
+interface AppreciationsFile { version: string; appreciations: BrainAppreciation[] }
+interface MissionsFile { version: string; missions: BrainMission[] }
+interface MissionTasksFile { version: string; mission_tasks: BrainMissionTask[] }
+
+const DEFAULT_TASKS: TasksFile = { version: '2.0', tasks: [] };
+const DEFAULT_PROJECTS: ProjectsFile = { version: '2.0', projects: [] };
+const DEFAULT_EVENTS: EventsFile = { version: '2.0', events: [] };
+const DEFAULT_AGENTS: AgentsFile = { version: '2.0', agents: [] };
+const DEFAULT_TICKETS: TicketsFile = { version: '2.0', tickets: [] };
+const DEFAULT_APPRECIATIONS: AppreciationsFile = { version: '2.0', appreciations: [] };
+const DEFAULT_MISSIONS: MissionsFile = { version: '2.0', missions: [] };
+const DEFAULT_MISSION_TASKS: MissionTasksFile = { version: '2.0', mission_tasks: [] };
+
+const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
+
+function matchesFilter<T>(item: T, filters: object): boolean {
+  for (const [key, value] of Object.entries(filters as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    if (key === 'limit') continue;
+    if (key === 'due_before') {
+      if (!(item as Record<string, unknown>)['due'] || (item as Record<string, unknown>)['due']! > value) return false;
+      continue;
+    }
+    if (key === 'due_after') {
+      if (!(item as Record<string, unknown>)['due'] || (item as Record<string, unknown>)['due']! < value) return false;
+      continue;
+    }
+    if (key === 'date_from') {
+      if ((item as Record<string, unknown>)['date']! < value) return false;
+      continue;
+    }
+    if (key === 'date_to') {
+      if ((item as Record<string, unknown>)['date']! > value) return false;
+      continue;
+    }
+    if (key === 'priority_min') {
+      if (((item as Record<string, unknown>)['priority'] as number) < (value as number)) return false;
+      continue;
+    }
+    if (key === 'priority_max') {
+      if (((item as Record<string, unknown>)['priority'] as number) > (value as number)) return false;
+      continue;
+    }
+    if ((item as Record<string, unknown>)[key] !== value) return false;
+  }
+  return true;
+}
+
+function applyLimit<T>(items: T[], limit?: number): T[] {
+  return limit != null && limit > 0 ? items.slice(0, limit) : items;
+}
+
+export class Collections {
+  constructor(private readonly store: JsonStore) {}
+
+  // === Tasks ===
+
+  async getTasks(filters: BrainTaskFilters = {}): Promise<BrainTask[]> {
+    const file = await this.store.read('tasks', DEFAULT_TASKS);
+    const filtered = file.tasks.filter(t => matchesFilter(t, filters));
+    filtered.sort((a, b) =>
+      (PRIORITY_ORDER[a.priority] ?? 9) - (PRIORITY_ORDER[b.priority] ?? 9)
+      || (a.due ?? '9999').localeCompare(b.due ?? '9999'),
+    );
+    return applyLimit(filtered, filters.limit);
+  }
+
+  async getTask(id: string): Promise<BrainTask | null> {
+    const file = await this.store.read('tasks', DEFAULT_TASKS);
+    return file.tasks.find(t => t.id === id) ?? null;
+  }
+
+  async addTask(task: BrainTask): Promise<BrainTask> {
+    const result = await this.store.modify('tasks', DEFAULT_TASKS, (file) => {
+      if (file.tasks.some(t => t.id === task.id)) {
+        throw new Error(`Task '${task.id}' already exists`);
+      }
+      return { ...file, tasks: [...file.tasks, task] };
+    });
+    return result.tasks.find(t => t.id === task.id)!;
+  }
+
+  async updateTask(id: string, updates: Partial<BrainTask>): Promise<BrainTask> {
+    let updated: BrainTask | undefined;
+    await this.store.modify('tasks', DEFAULT_TASKS, (file) => {
+      const idx = file.tasks.findIndex(t => t.id === id);
+      if (idx === -1) throw new Error(`Task '${id}' not found`);
+      const tasks = [...file.tasks];
+      updated = { ...tasks[idx]!, ...updates, id, updated: today() } as BrainTask;
+      tasks[idx] = updated;
+      return { ...file, tasks };
+    });
+    return updated!;
+  }
+
+  // === Projects ===
+
+  async getProjects(filters: BrainProjectFilters = {}): Promise<BrainProject[]> {
+    const file = await this.store.read('projects', DEFAULT_PROJECTS);
+    const filtered = file.projects.filter(p => matchesFilter(p, filters));
+    filtered.sort((a, b) => a.priority - b.priority);
+    return applyLimit(filtered, filters.limit);
+  }
+
+  async getProject(id: string): Promise<BrainProject | null> {
+    const file = await this.store.read('projects', DEFAULT_PROJECTS);
+    return file.projects.find(p => p.id === id) ?? null;
+  }
+
+  async addProject(project: BrainProject): Promise<BrainProject> {
+    const result = await this.store.modify('projects', DEFAULT_PROJECTS, (file) => {
+      if (file.projects.some(p => p.id === project.id)) {
+        throw new Error(`Project '${project.id}' already exists`);
+      }
+      return { ...file, projects: [...file.projects, project] };
+    });
+    return result.projects.find(p => p.id === project.id)!;
+  }
+
+  async updateProject(id: string, updates: Partial<BrainProject>): Promise<BrainProject> {
+    let updated: BrainProject | undefined;
+    await this.store.modify('projects', DEFAULT_PROJECTS, (file) => {
+      const idx = file.projects.findIndex(p => p.id === id);
+      if (idx === -1) throw new Error(`Project '${id}' not found`);
+      const projects = [...file.projects];
+      updated = { ...projects[idx]!, ...updates, id, updated: today() } as BrainProject;
+      projects[idx] = updated;
+      return { ...file, projects };
+    });
+    return updated!;
+  }
+
+  // === Events ===
+
+  async getEvents(filters: BrainEventFilters = {}): Promise<BrainEvent[]> {
+    const file = await this.store.read('events', DEFAULT_EVENTS);
+    const filtered = file.events.filter(e => matchesFilter(e, filters));
+    filtered.sort((a, b) => a.date.localeCompare(b.date) || (a.time ?? '').localeCompare(b.time ?? ''));
+    return applyLimit(filtered, filters.limit);
+  }
+
+  async getEvent(id: string): Promise<BrainEvent | null> {
+    const file = await this.store.read('events', DEFAULT_EVENTS);
+    return file.events.find(e => e.id === id) ?? null;
+  }
+
+  async addEvent(event: BrainEvent): Promise<BrainEvent> {
+    const result = await this.store.modify('events', DEFAULT_EVENTS, (file) => {
+      if (file.events.some(e => e.id === event.id)) {
+        throw new Error(`Event '${event.id}' already exists`);
+      }
+      return { ...file, events: [...file.events, event] };
+    });
+    return result.events.find(e => e.id === event.id)!;
+  }
+
+  async updateEvent(id: string, updates: Partial<BrainEvent>): Promise<BrainEvent> {
+    let updated: BrainEvent | undefined;
+    await this.store.modify('events', DEFAULT_EVENTS, (file) => {
+      const idx = file.events.findIndex(e => e.id === id);
+      if (idx === -1) throw new Error(`Event '${id}' not found`);
+      const events = [...file.events];
+      updated = { ...events[idx]!, ...updates, id } as BrainEvent;
+      events[idx] = updated;
+      return { ...file, events };
+    });
+    return updated!;
+  }
+
+  // === Agents ===
+
+  async getAgents(filters: { status?: string; project?: string } = {}): Promise<BrainAgent[]> {
+    const file = await this.store.read('agents', DEFAULT_AGENTS);
+    return file.agents.filter(a => matchesFilter(a, filters));
+  }
+
+  async updateAgent(id: string, updates: Partial<BrainAgent>): Promise<BrainAgent> {
+    let updated: BrainAgent | undefined;
+    await this.store.modify('agents', DEFAULT_AGENTS, (file) => {
+      const idx = file.agents.findIndex(a => a.id === id);
+      if (idx === -1) {
+        // Auto-create agent entries
+        updated = { id, project: '', status: 'active', updated: new Date().toISOString(), ...updates } as BrainAgent;
+        return { ...file, agents: [...file.agents, updated] };
+      }
+      const agents = [...file.agents];
+      updated = { ...agents[idx]!, ...updates, id, updated: new Date().toISOString() } as BrainAgent;
+      agents[idx] = updated;
+      return { ...file, agents };
+    });
+    return updated!;
+  }
+
+  // === Tickets ===
+
+  async getTickets(filters: { status?: number; priority?: number; limit?: number } = {}): Promise<BrainTicket[]> {
+    const file = await this.store.read('tickets', DEFAULT_TICKETS);
+    let filtered = file.tickets;
+    if (filters.status !== undefined) filtered = filtered.filter(t => t.status === filters.status);
+    if (filters.priority !== undefined) filtered = filtered.filter(t => t.priority === filters.priority);
+    return applyLimit(filtered, filters.limit);
+  }
+
+  // === Appreciations ===
+
+  async getAppreciations(): Promise<BrainAppreciation[]> {
+    const file = await this.store.read('appreciations', DEFAULT_APPRECIATIONS);
+    return file.appreciations;
+  }
+
+  async addAppreciation(appreciation: BrainAppreciation): Promise<BrainAppreciation> {
+    await this.store.modify('appreciations', DEFAULT_APPRECIATIONS, (file) => ({
+      ...file,
+      appreciations: [...file.appreciations, appreciation],
+    }));
+    return appreciation;
+  }
+
+  // === Missions ===
+
+  async getMissions(filters: BrainMissionFilters = {}): Promise<BrainMission[]> {
+    const file = await this.store.read('missions', DEFAULT_MISSIONS);
+    const filtered = file.missions.filter(m => matchesFilter(m, filters));
+    return applyLimit(filtered, filters.limit);
+  }
+
+  async getMission(id: string): Promise<BrainMission | null> {
+    const file = await this.store.read('missions', DEFAULT_MISSIONS);
+    return file.missions.find(m => m.id === id) ?? null;
+  }
+
+  async addMission(mission: BrainMission): Promise<BrainMission> {
+    const result = await this.store.modify('missions', DEFAULT_MISSIONS, (file) => {
+      if (file.missions.some(m => m.id === mission.id)) {
+        throw new Error(`Mission '${mission.id}' already exists`);
+      }
+      return { ...file, missions: [...file.missions, mission] };
+    });
+    return result.missions.find(m => m.id === mission.id)!;
+  }
+
+  async updateMission(id: string, updates: Partial<BrainMission>): Promise<BrainMission> {
+    let updated: BrainMission | undefined;
+    await this.store.modify('missions', DEFAULT_MISSIONS, (file) => {
+      const idx = file.missions.findIndex(m => m.id === id);
+      if (idx === -1) throw new Error(`Mission '${id}' not found`);
+      const missions = [...file.missions];
+      updated = { ...missions[idx]!, ...updates, id, updated: today() } as BrainMission;
+      missions[idx] = updated;
+      return { ...file, missions };
+    });
+    return updated!;
+  }
+
+  async getMissionSummary(id: string): Promise<BrainMissionSummary | null> {
+    const mission = await this.getMission(id);
+    if (!mission) return null;
+
+    const tasks = await this.getMissionTasks({ mission_id: id });
+    const completed = tasks.filter(t => t.status === 'done');
+    const completedIds = new Set(completed.map(t => t.id));
+
+    const nextAvailable = tasks.filter(t =>
+      t.status !== 'done' && t.status !== 'cancelled' && t.status !== 'blocked'
+      && t.dependencies.every(dep => completedIds.has(dep))
+      && !t.assigned_to,
+    );
+
+    const blockedTasks = tasks.filter(t =>
+      t.status === 'blocked'
+      || (t.status !== 'done' && t.status !== 'cancelled'
+        && !t.dependencies.every(dep => completedIds.has(dep))),
+    );
+
+    return {
+      ...mission,
+      task_count: tasks.length,
+      completed_count: completed.length,
+      progress: tasks.length > 0 ? Math.round((completed.length / tasks.length) * 100) : 0,
+      next_available: nextAvailable,
+      blocked_tasks: blockedTasks,
+    };
+  }
+
+  // === Mission Tasks ===
+
+  async getMissionTasks(filters: BrainMissionTaskFilters): Promise<BrainMissionTask[]> {
+    const file = await this.store.read('mission_tasks', DEFAULT_MISSION_TASKS);
+    const filtered = file.mission_tasks.filter(t => matchesFilter(t, filters));
+    filtered.sort((a, b) => a.order - b.order);
+    return filtered;
+  }
+
+  async addMissionTask(task: BrainMissionTask): Promise<BrainMissionTask> {
+    const result = await this.store.modify('mission_tasks', DEFAULT_MISSION_TASKS, (file) => {
+      if (file.mission_tasks.some(t => t.id === task.id && t.mission_id === task.mission_id)) {
+        throw new Error(`Mission task '${task.id}' already exists in mission '${task.mission_id}'`);
+      }
+      return { ...file, mission_tasks: [...file.mission_tasks, task] };
+    });
+    return result.mission_tasks.find(t => t.id === task.id && t.mission_id === task.mission_id)!;
+  }
+
+  async updateMissionTask(missionId: string, taskId: string, updates: Partial<BrainMissionTask>): Promise<BrainMissionTask> {
+    let updated: BrainMissionTask | undefined;
+    await this.store.modify('mission_tasks', DEFAULT_MISSION_TASKS, (file) => {
+      const idx = file.mission_tasks.findIndex(t => t.id === taskId && t.mission_id === missionId);
+      if (idx === -1) throw new Error(`Mission task '${taskId}' not found in mission '${missionId}'`);
+      const tasks = [...file.mission_tasks];
+      updated = { ...tasks[idx]!, ...updates, id: taskId, mission_id: missionId, updated: today() } as BrainMissionTask;
+      if (updates.status === 'done' && !updated.completed_at) {
+        updated = { ...updated, completed_at: new Date().toISOString() };
+      }
+      tasks[idx] = updated;
+      return { ...file, mission_tasks: tasks };
+    });
+    return updated!;
+  }
+
+  // === Computed: Today ===
+
+  async getToday(date?: string): Promise<BrainTodaySummary> {
+    const d = date ?? today();
+    const weekFromNow = new Date(Date.now() + 7 * 86400000).toISOString().slice(0, 10);
+    const staleCutoff = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 10);
+
+    const [tasks, projects, events, agents, missions] = await Promise.all([
+      this.getTasks(),
+      this.getProjects(),
+      this.getEvents(),
+      this.getAgents(),
+      this.getMissions({ status: 'active' }),
+    ]);
+
+    const activeTasks = tasks.filter(t => t.status !== 'done' && t.status !== 'cancelled');
+    const eventsToday = events.filter(e => e.date === d);
+    const eventsUpcoming = events.filter(e => e.date > d && e.date <= weekFromNow);
+    const tasksNearTerm = activeTasks.filter(t => t.due && t.due >= d && t.due <= weekFromNow);
+    const tasksBlocked = activeTasks.filter(t => t.status === 'blocked');
+    const tasksStale = activeTasks.filter(t => t.status === 'in-progress' && t.updated < staleCutoff);
+    const tasksAlmostDone = activeTasks.filter(t => t.progress != null && t.progress >= 80);
+
+    const missionSummaries: BrainMissionSummary[] = [];
+    for (const m of missions) {
+      const summary = await this.getMissionSummary(m.id);
+      if (summary) missionSummaries.push(summary);
+    }
+
+    const tasksByStatus: Record<string, number> = {};
+    const tasksByDomain: Record<string, number> = {};
+    for (const t of tasks) {
+      tasksByStatus[t.status] = (tasksByStatus[t.status] ?? 0) + 1;
+      tasksByDomain[t.domain] = (tasksByDomain[t.domain] ?? 0) + 1;
+    }
+    const projectsByStatus: Record<string, number> = {};
+    for (const p of projects) {
+      projectsByStatus[p.status] = (projectsByStatus[p.status] ?? 0) + 1;
+    }
+
+    return {
+      date: d,
+      events_today: eventsToday,
+      events_upcoming: eventsUpcoming,
+      tasks_near_term: tasksNearTerm,
+      tasks_blocked: tasksBlocked,
+      tasks_stale: tasksStale,
+      tasks_almost_done: tasksAlmostDone,
+      active_missions: missionSummaries,
+      stats: {
+        tasks: tasks.length,
+        projects: projects.length,
+        events: events.length,
+        agents: agents.length,
+        tickets: (await this.getTickets()).length,
+        missions: (await this.getMissions()).length,
+        tasks_by_status: tasksByStatus,
+        tasks_by_domain: tasksByDomain,
+        projects_by_status: projectsByStatus,
+      },
+    };
+  }
+
+  // === Computed: Stale ===
+
+  async getStale(days: number = 7): Promise<BrainStaleReport> {
+    const cutoff = new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
+    const tasks = await this.getTasks();
+    const projects = await this.getProjects();
+
+    return {
+      days,
+      tasks: tasks.filter(t => t.status === 'in-progress' && t.updated < cutoff),
+      projects: projects.filter(p => p.status === 'active' && p.updated < cutoff),
+    };
+  }
+
+  // === Computed: Stats ===
+
+  async getStats(): Promise<BrainStats> {
+    const [tasks, projects, events, agents, tickets, missions] = await Promise.all([
+      this.getTasks(),
+      this.getProjects(),
+      this.getEvents(),
+      this.getAgents(),
+      this.getTickets(),
+      this.getMissions(),
+    ]);
+
+    const tasksByStatus: Record<string, number> = {};
+    const tasksByDomain: Record<string, number> = {};
+    for (const t of tasks) {
+      tasksByStatus[t.status] = (tasksByStatus[t.status] ?? 0) + 1;
+      tasksByDomain[t.domain] = (tasksByDomain[t.domain] ?? 0) + 1;
+    }
+    const projectsByStatus: Record<string, number> = {};
+    for (const p of projects) {
+      projectsByStatus[p.status] = (projectsByStatus[p.status] ?? 0) + 1;
+    }
+
+    return {
+      tasks: tasks.length,
+      projects: projects.length,
+      events: events.length,
+      agents: agents.length,
+      tickets: tickets.length,
+      missions: missions.length,
+      tasks_by_status: tasksByStatus,
+      tasks_by_domain: tasksByDomain,
+      projects_by_status: projectsByStatus,
+    };
+  }
+
+  // === Computed: Search ===
+
+  async search(query: string, collection?: string): Promise<BrainSearchResult[]> {
+    const q = query.toLowerCase();
+    const results: BrainSearchResult[] = [];
+
+    const searchIn = (items: Array<{ id: string; title: string; notes?: string | null }>, collectionName: string) => {
+      for (const item of items) {
+        const titleMatch = item.title.toLowerCase().includes(q);
+        const notesMatch = item.notes?.toLowerCase().includes(q);
+        if (titleMatch || notesMatch) {
+          results.push({
+            collection: collectionName,
+            id: item.id,
+            title: item.title,
+            match_context: titleMatch ? item.title : (item.notes?.substring(0, 200) ?? ''),
+            score: titleMatch ? 1.0 : 0.5,
+          });
+        }
+      }
+    };
+
+    if (!collection || collection === 'tasks') searchIn(await this.getTasks(), 'tasks');
+    if (!collection || collection === 'projects') {
+      const projects = await this.getProjects();
+      for (const p of projects) {
+        const titleMatch = p.name.toLowerCase().includes(q);
+        const notesMatch = p.notes?.toLowerCase().includes(q);
+        if (titleMatch || notesMatch) {
+          results.push({
+            collection: 'projects',
+            id: p.id,
+            title: p.name,
+            match_context: titleMatch ? p.name : (p.notes?.substring(0, 200) ?? ''),
+            score: titleMatch ? 1.0 : 0.5,
+          });
+        }
+      }
+    }
+    if (!collection || collection === 'events') searchIn(await this.getEvents(), 'events');
+    if (!collection || collection === 'missions') searchIn(await this.getMissions(), 'missions');
+
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+
+  // === Computed: Audit ===
+
+  async audit(): Promise<BrainAuditResult> {
+    const tasks = await this.getTasks();
+    const projects = await this.getProjects();
+    const taskIds = new Set(tasks.map(t => t.id));
+    const projectIds = new Set(projects.map(p => p.id));
+    const allIds = new Set([...taskIds, ...projectIds]);
+
+    const orphanRefs: string[] = [];
+    const brokenDependencies: string[] = [];
+    const missingRequiredFields: string[] = [];
+    const duplicateIds: string[] = [];
+
+    // Check for duplicate task IDs
+    const seenTaskIds = new Set<string>();
+    for (const t of tasks) {
+      if (seenTaskIds.has(t.id)) duplicateIds.push(`task:${t.id}`);
+      seenTaskIds.add(t.id);
+    }
+
+    // Check task references
+    for (const t of tasks) {
+      if (t.project && !projectIds.has(t.project)) {
+        orphanRefs.push(`task:${t.id} -> project:${t.project}`);
+      }
+      for (const dep of t.blocked_by ?? []) {
+        if (!allIds.has(dep)) brokenDependencies.push(`task:${t.id} blocked_by:${dep}`);
+      }
+      for (const dep of t.blocks ?? []) {
+        if (!allIds.has(dep)) brokenDependencies.push(`task:${t.id} blocks:${dep}`);
+      }
+      if (!t.title) missingRequiredFields.push(`task:${t.id} missing title`);
+    }
+
+    return { orphan_refs: orphanRefs, broken_dependencies: brokenDependencies, missing_required_fields: missingRequiredFields, duplicate_ids: duplicateIds };
+  }
+}

packages/brain/src/storage/json-store.ts

@@ -0,0 +1,156 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import * as lockfile from 'proper-lockfile';
+
+export interface JsonStoreOptions {
+  dataDir: string;
+}
+
+const LOCK_OPTIONS = { retries: { retries: 5, minTimeout: 100 } };
+
+/**
+ * JSON file-backed storage with file locking for concurrent access.
+ * One file per collection. In-memory cache for fast reads.
+ *
+ * Known constraint: Cache TTL means multi-instance deployments against
+ * the same data directory may see stale reads for up to CACHE_TTL_MS.
+ * Single-instance is the supported topology for Phase 1.
+ */
+export class JsonStore {
+  private readonly dataDir: string;
+  private readonly cache = new Map<string, { data: unknown; loadedAt: number }>();
+  private static readonly CACHE_TTL_MS = 5_000;
+
+  constructor(options: JsonStoreOptions) {
+    this.dataDir = options.dataDir;
+  }
+
+  async init(): Promise<void> {
+    if (!existsSync(this.dataDir)) {
+      await mkdir(this.dataDir, { recursive: true });
+    }
+  }
+
+  private filePath(collection: string): string {
+    return join(this.dataDir, `${collection}.json`);
+  }
+
+  private isCacheValid(collection: string): boolean {
+    const cached = this.cache.get(collection);
+    if (!cached) return false;
+    return Date.now() - cached.loadedAt < JsonStore.CACHE_TTL_MS;
+  }
+
+  /**
+   * Ensure a file exists for locking. Uses a separate lock on the
+   * directory to prevent race conditions during file creation.
+   */
+  private async ensureFile(path: string, defaultContent: string): Promise<void> {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true });
+    }
+    if (!existsSync(path)) {
+      // Lock the directory to serialize file creation
+      let releaseDir: (() => Promise<void>) | undefined;
+      try {
+        releaseDir = await lockfile.lock(dir, LOCK_OPTIONS);
+        // Double-check after acquiring lock
+        if (!existsSync(path)) {
+          await writeFile(path, defaultContent, 'utf-8');
+        }
+      } finally {
+        if (releaseDir) await releaseDir();
+      }
+    }
+  }
+
+  /**
+   * Read a collection file. Returns parsed JSON or default if file doesn't exist.
+   */
+  async read<T>(collection: string, defaultValue: T): Promise<T> {
+    if (this.isCacheValid(collection)) {
+      return this.cache.get(collection)!.data as T;
+    }
+
+    const path = this.filePath(collection);
+    if (!existsSync(path)) {
+      this.cache.set(collection, { data: defaultValue, loadedAt: Date.now() });
+      return defaultValue;
+    }
+
+    try {
+      const raw = await readFile(path, 'utf-8');
+      const data = JSON.parse(raw) as T;
+      this.cache.set(collection, { data, loadedAt: Date.now() });
+      return data;
+    } catch {
+      return defaultValue;
+    }
+  }
+
+  /**
+   * Write a collection file with file locking.
+   */
+  async write(collection: string, data: unknown): Promise<void> {
+    const path = this.filePath(collection);
+    await this.ensureFile(path, '{}');
+
+    let release: (() => Promise<void>) | undefined;
+    try {
+      release = await lockfile.lock(path, LOCK_OPTIONS);
+      await writeFile(path, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+      this.cache.set(collection, { data, loadedAt: Date.now() });
+    } finally {
+      if (release) await release();
+    }
+  }
+
+  /**
+   * Read-modify-write with file locking. The modifier function receives
+   * the current data and returns the updated data.
+   */
+  async modify<T>(
+    collection: string,
+    defaultValue: T,
+    modifier: (current: T) => T | Promise<T>,
+  ): Promise<T> {
+    const path = this.filePath(collection);
+    await this.ensureFile(path, JSON.stringify(defaultValue, null, 2) + '\n');
+
+    let release: (() => Promise<void>) | undefined;
+    try {
+      release = await lockfile.lock(path, LOCK_OPTIONS);
+
+      let current: T;
+      try {
+        const raw = await readFile(path, 'utf-8');
+        current = JSON.parse(raw) as T;
+      } catch {
+        current = defaultValue;
+      }
+
+      const updated = await modifier(current);
+      await writeFile(path, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
+      this.cache.set(collection, { data: updated, loadedAt: Date.now() });
+      return updated;
+    } finally {
+      if (release) await release();
+    }
+  }
+
+  /**
+   * Invalidate cache for a collection.
+   */
+  invalidate(collection: string): void {
+    this.cache.delete(collection);
+  }
+
+  /**
+   * Invalidate all cached data.
+   */
+  invalidateAll(): void {
+    this.cache.clear();
+  }
+}

packages/brain/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

packages/types/src/index.ts

@@ -340,3 +340,315 @@ export interface WizardState {
   readonly runtimes: RuntimeState;
   readonly selectedSkills: readonly string[];
 }
+
+// === Brain (Structured Data) ===
+
+export type BrainDomain =
+  | 'work'
+  | 'software-dev'
+  | 'homelab'
+  | 'family'
+  | 'marriage'
+  | 'finances'
+  | 'fitness'
+  | 'music'
+  | 'home-improvement'
+  | 'woodworking'
+  | 'home'
+  | 'consulting'
+  | 'personal';
+
+export type BrainTaskStatus =
+  | 'backlog'
+  | 'scheduled'
+  | 'in-progress'
+  | 'blocked'
+  | 'done'
+  | 'cancelled';
+
+export type BrainProjectStatus =
+  | 'planning'
+  | 'active'
+  | 'paused'
+  | 'blocked'
+  | 'completed'
+  | 'archived';
+
+export type BrainAgentStatus = 'active' | 'idle' | 'blocked' | 'completed';
+
+export type BrainEventType =
+  | 'meeting'
+  | 'deadline'
+  | 'maintenance'
+  | 'event'
+  | 'recurring'
+  | 'milestone'
+  | 'task'
+  | 'constraint'
+  | 'client-work'
+  | 'appointment'
+  | 'reminder'
+  | 'conflict'
+  | 'time-off';
+
+export type BrainEventStatus =
+  | 'scheduled'
+  | 'confirmed'
+  | 'tentative'
+  | 'completed'
+  | 'cancelled'
+  | 'done'
+  | 'blocked'
+  | 'postponed'
+  | 'deferred'
+  | 'in-progress'
+  | 'pending-approval'
+  | 'canceled'
+  | 'needs-resolution';
+
+export type BrainMissionStatus =
+  | 'planning'
+  | 'active'
+  | 'blocked'
+  | 'completed'
+  | 'cancelled';
+
+// --- Brain: Task ---
+
+export interface BrainTask {
+  readonly id: string;
+  readonly title: string;
+  readonly domain: BrainDomain;
+  readonly project?: string | null;
+  readonly priority: TaskPriority;
+  readonly status: BrainTaskStatus;
+  readonly progress?: number | null;
+  readonly due?: string | null;
+  readonly blocks?: readonly string[];
+  readonly blocked_by?: readonly string[];
+  readonly related?: readonly string[];
+  readonly canonical_source?: string | null;
+  readonly assignee?: string | null;
+  readonly created: string;
+  readonly updated: string;
+  readonly notes?: string | null;
+  readonly notes_nontechnical?: string | null;
+}
+
+// --- Brain: Project ---
+
+export interface BrainProject {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string | null;
+  readonly domain: BrainDomain;
+  readonly status: BrainProjectStatus;
+  readonly priority: number;
+  readonly progress?: number | null;
+  readonly repo?: string | null;
+  readonly branch?: string | null;
+  readonly current_milestone?: string | null;
+  readonly next_milestone?: string | null;
+  readonly blocker?: string | null;
+  readonly owner?: string | null;
+  readonly docs_path?: string | null;
+  readonly created: string;
+  readonly updated: string;
+  readonly notes?: string | null;
+  readonly notes_nontechnical?: string | null;
+}
+
+// --- Brain: Event ---
+
+export interface BrainEvent {
+  readonly id: string;
+  readonly title: string;
+  readonly date: string;
+  readonly end_date?: string | null;
+  readonly time?: string | null;
+  readonly end_time?: string | null;
+  readonly domain: BrainDomain;
+  readonly type: BrainEventType;
+  readonly status?: BrainEventStatus;
+  readonly priority?: TaskPriority | null;
+  readonly recur?: boolean | null;
+  readonly recur_rate?: string | null;
+  readonly recur_start?: string | null;
+  readonly recur_end?: string | null;
+  readonly location?: string | null;
+  readonly project?: string | null;
+  readonly related_task?: string | null;
+  readonly related_tasks?: readonly string[];
+  readonly notes?: string | null;
+  readonly gcal_id?: string | null;
+  readonly ics_uid?: string | null;
+}
+
+// --- Brain: Agent ---
+
+export interface BrainAgent {
+  readonly id: string;
+  readonly project: string;
+  readonly focus?: string | null;
+  readonly repo?: string | null;
+  readonly branch?: string | null;
+  readonly status: BrainAgentStatus;
+  readonly workload?: 'light' | 'medium' | 'heavy' | null;
+  readonly next_step?: string | null;
+  readonly blocker?: string | null;
+  readonly updated: string;
+}
+
+// --- Brain: Ticket ---
+
+export interface BrainTicket {
+  readonly id: string;
+  readonly title: string;
+  readonly status: number;
+  readonly priority: number;
+  readonly urgency: number;
+  readonly impact: number;
+  readonly date_creation: string;
+  readonly date_mod: string;
+  readonly content?: string | null;
+  readonly assigned_to?: string | null;
+}
+
+// --- Brain: Appreciation ---
+
+export interface BrainAppreciation {
+  readonly date: string;
+  readonly from: 'jason' | 'melanie';
+  readonly to: 'jason' | 'melanie';
+  readonly text: string;
+}
+
+// --- Brain: Mission ---
+
+export interface BrainMission {
+  readonly id: string;
+  readonly title: string;
+  readonly project: string;
+  readonly prd_path?: string | null;
+  readonly status: BrainMissionStatus;
+  readonly created: string;
+  readonly updated: string;
+  readonly notes?: string | null;
+}
+
+// --- Brain: Mission Task ---
+
+export interface BrainMissionTask {
+  readonly id: string;
+  readonly mission_id: string;
+  readonly title: string;
+  readonly phase?: string | null;
+  readonly status: BrainTaskStatus;
+  readonly priority: TaskPriority;
+  readonly dependencies: readonly string[];
+  readonly assigned_to?: string | null;
+  readonly pr?: string | null;
+  readonly order: number;
+  readonly created: string;
+  readonly updated: string;
+  readonly completed_at?: string | null;
+  readonly notes?: string | null;
+}
+
+// --- Brain: Filter/Query Types ---
+
+export interface BrainTaskFilters {
+  readonly status?: BrainTaskStatus;
+  readonly priority?: TaskPriority;
+  readonly domain?: BrainDomain;
+  readonly project?: string;
+  readonly due_before?: string;
+  readonly due_after?: string;
+  readonly assignee?: string;
+  readonly limit?: number;
+}
+
+export interface BrainProjectFilters {
+  readonly status?: BrainProjectStatus;
+  readonly domain?: BrainDomain;
+  readonly priority_min?: number;
+  readonly priority_max?: number;
+  readonly limit?: number;
+}
+
+export interface BrainEventFilters {
+  readonly date_from?: string;
+  readonly date_to?: string;
+  readonly domain?: BrainDomain;
+  readonly type?: BrainEventType;
+  readonly status?: BrainEventStatus;
+  readonly limit?: number;
+}
+
+export interface BrainMissionFilters {
+  readonly status?: BrainMissionStatus;
+  readonly project?: string;
+  readonly limit?: number;
+}
+
+export interface BrainMissionTaskFilters {
+  readonly mission_id: string;
+  readonly status?: BrainTaskStatus;
+  readonly phase?: string;
+  readonly priority?: TaskPriority;
+}
+
+// --- Brain: Computed Response Types ---
+
+export interface BrainMissionSummary extends BrainMission {
+  readonly task_count: number;
+  readonly completed_count: number;
+  readonly progress: number;
+  readonly next_available: readonly BrainMissionTask[];
+  readonly blocked_tasks: readonly BrainMissionTask[];
+}
+
+export interface BrainTodaySummary {
+  readonly date: string;
+  readonly events_today: readonly BrainEvent[];
+  readonly events_upcoming: readonly BrainEvent[];
+  readonly tasks_near_term: readonly BrainTask[];
+  readonly tasks_blocked: readonly BrainTask[];
+  readonly tasks_stale: readonly BrainTask[];
+  readonly tasks_almost_done: readonly BrainTask[];
+  readonly active_missions: readonly BrainMissionSummary[];
+  readonly stats: BrainStats;
+}
+
+export interface BrainStats {
+  readonly tasks: number;
+  readonly projects: number;
+  readonly events: number;
+  readonly agents: number;
+  readonly tickets: number;
+  readonly missions: number;
+  readonly tasks_by_status: Readonly<Record<string, number>>;
+  readonly tasks_by_domain: Readonly<Record<string, number>>;
+  readonly projects_by_status: Readonly<Record<string, number>>;
+}
+
+export interface BrainStaleReport {
+  readonly days: number;
+  readonly tasks: readonly BrainTask[];
+  readonly projects: readonly BrainProject[];
+}
+
+export interface BrainAuditResult {
+  readonly orphan_refs: readonly string[];
+  readonly broken_dependencies: readonly string[];
+  readonly missing_required_fields: readonly string[];
+  readonly duplicate_ids: readonly string[];
+}
+
+export interface BrainSearchResult {
+  readonly collection: string;
+  readonly id: string;
+  readonly title: string;
+  readonly match_context: string;
+  readonly score: number;
+}