bonecode 1.0.0

package/bone/output/rag/src/notify.ts

@@ -0,0 +1,99 @@
+// Generated by BoneScript compiler.
+// Notification service — fires on event emissions.
+// Configure NOTIFY_PROVIDER=resend|sendgrid|log (default: log)
+// Set NOTIFY_API_KEY and NOTIFY_FROM_EMAIL in .env
+
+import { SystemEvent } from "./events";
+
+export type NotifyProvider = "resend" | "sendgrid" | "log";
+
+const PROVIDER = (process.env.NOTIFY_PROVIDER || "log") as NotifyProvider;
+const API_KEY = process.env.NOTIFY_API_KEY || "";
+const FROM_EMAIL = process.env.NOTIFY_FROM_EMAIL || "noreply@example.com";
+
+export interface NotifyMessage {
+  to: string;
+  subject: string;
+  body: string;
+}
+
+async function sendEmail(msg: NotifyMessage): Promise<void> {
+  if (PROVIDER === "log") {
+    console.log(`[notify] ${msg.subject} → ${msg.to}`);
+    return;
+  }
+  if (PROVIDER === "resend") {
+    const res = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ from: FROM_EMAIL, to: msg.to, subject: msg.subject, html: msg.body }),
+    });
+    if (!res.ok) throw new Error(`Resend error: ${res.status}`);
+    return;
+  }
+  if (PROVIDER === "sendgrid") {
+    const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
+      method: "POST",
+      headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ personalizations: [{ to: [{ email: msg.to }] }], from: { email: FROM_EMAIL }, subject: msg.subject, content: [{ type: "text/html", value: msg.body }] }),
+    });
+    if (!res.ok) throw new Error(`SendGrid error: ${res.status}`);
+    return;
+  }
+}
+
+// Handler for CodebaseIngestionStarted
+export async function notifyCodebaseIngestionStarted(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "CodebaseIngestionStarted notification",
+    body: `<p>Event <strong>CodebaseIngestionStarted</strong> occurred.</p><pre>${JSON.stringify(event.payload, null, 2)}</pre>`,
+  });
+}
+
+// Handler for CodebaseIngestionCompleted
+export async function notifyCodebaseIngestionCompleted(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "CodebaseIngestionCompleted notification",
+    body: `<p>Event <strong>CodebaseIngestionCompleted</strong> occurred.</p><pre>${JSON.stringify(event.payload, null, 2)}</pre>`,
+  });
+}
+
+// Handler for FileIndexed
+export async function notifyFileIndexed(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "FileIndexed notification",
+    body: `<p>Event <strong>FileIndexed</strong> occurred.</p><pre>${JSON.stringify(event.payload, null, 2)}</pre>`,
+  });
+}
+
+// Handler for MemoryStored
+export async function notifyMemoryStored(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "MemoryStored notification",
+    body: `<p>Event <strong>MemoryStored</strong> occurred.</p><pre>${JSON.stringify(event.payload, null, 2)}</pre>`,
+  });
+}
+
+export function registerNotificationHandlers(eventBus: any): void {
+  // TODO: implement recipient lookup per event type
+  // eventBus.subscribe("CodebaseIngestionStarted", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifyCodebaseIngestionStarted(event, recipientEmail);
+  // });
+  // eventBus.subscribe("CodebaseIngestionCompleted", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifyCodebaseIngestionCompleted(event, recipientEmail);
+  // });
+  // eventBus.subscribe("FileIndexed", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifyFileIndexed(event, recipientEmail);
+  // });
+  // eventBus.subscribe("MemoryStored", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifyMemoryStored(event, recipientEmail);
+  // });
+}

package/bone/output/rag/src/routes/code_chunk.ts

@@ -0,0 +1,75 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: CodeChunkService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+export const codeChunksRouter = Router();
+
+// CREATE
+codeChunksRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { code_file_id, knowledge_base_id, project_id, content, start_line, end_line, chunk_index, language, symbol_name, symbol_type, metadata } = req.body;
+    const sql = `INSERT INTO code_chunks (id, code_file_id, knowledge_base_id, project_id, content, start_line, end_line, chunk_index, language, symbol_name, symbol_type, metadata) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) RETURNING *`;
+    const rows = await query(sql, [id, code_file_id, knowledge_base_id, project_id, content, start_line, end_line, chunk_index, language, symbol_name, symbol_type, metadata]);
+    counter("entity.created", { entity: "CodeChunk" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+codeChunksRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM code_chunks WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+codeChunksRouter.get("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT code_chunks.*, row_to_json(code_file.*) as code_file FROM code_chunks LEFT JOIN code_files code_file ON code_chunks.code_file_id = code_file.id ORDER BY code_chunks.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM code_chunks`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+codeChunksRouter.put("/:id", requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE code_chunks SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+codeChunksRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM code_chunks WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/rag/src/routes/code_file.ts

@@ -0,0 +1,101 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: CodeFileService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionCodeFile, CODEFILE_INITIAL } from "../state_machines/code_file";
+
+export const codeFilesRouter = Router();
+
+// CREATE
+codeFilesRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { knowledge_base_id, project_id, file_path, language, file_hash, file_size_bytes, total_chunks, last_modified_at, metadata } = req.body;
+    const state = CODEFILE_INITIAL;
+    const sql = `INSERT INTO code_files (id, knowledge_base_id, project_id, file_path, language, file_hash, file_size_bytes, total_chunks, last_modified_at, metadata, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) RETURNING *`;
+    const rows = await query(sql, [id, knowledge_base_id, project_id, file_path, language, file_hash, file_size_bytes, total_chunks, last_modified_at, metadata, state]);
+    counter("entity.created", { entity: "CodeFile" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+codeFilesRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM code_files WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+codeFilesRouter.get("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT code_files.*, row_to_json(knowledge_base.*) as knowledge_base FROM code_files LEFT JOIN knowledge_bases knowledge_base ON code_files.knowledge_base_id = knowledge_base.id ORDER BY code_files.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM code_files`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+codeFilesRouter.put("/:id", requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM code_files WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionCodeFile(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE code_files SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+codeFilesRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM code_files WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// RELATION: chunks (has_many CodeChunk)
+codeFilesRouter.get("/:id/chunks", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM code_chunks WHERE code_file_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM code_chunks WHERE code_file_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/rag/src/routes/indexing_job.ts

@@ -0,0 +1,87 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: IndexingJobService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionIndexingJob, INDEXINGJOB_INITIAL } from "../state_machines/indexing_job";
+
+export const indexingJobsRouter = Router();
+
+// CREATE
+indexingJobsRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { knowledge_base_id, project_id, job_type, file_paths, files_total, files_processed, chunks_total, chunks_embedded, error } = req.body;
+    const state = INDEXINGJOB_INITIAL;
+    const sql = `INSERT INTO indexing_jobs (id, knowledge_base_id, project_id, job_type, file_paths, files_total, files_processed, chunks_total, chunks_embedded, error, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11) RETURNING *`;
+    const rows = await query(sql, [id, knowledge_base_id, project_id, job_type, file_paths, files_total, files_processed, chunks_total, chunks_embedded, error, state]);
+    counter("entity.created", { entity: "IndexingJob" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+indexingJobsRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM indexing_jobs WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+indexingJobsRouter.get("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM indexing_jobs ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM indexing_jobs`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+indexingJobsRouter.put("/:id", requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM indexing_jobs WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionIndexingJob(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE indexing_jobs SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+indexingJobsRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM indexing_jobs WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});

package/bone/output/rag/src/routes/knowledge_base.ts

@@ -0,0 +1,230 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: KnowledgeBaseService
+import { Router, Request, Response } from "express";
+import { v4 as uuid } from "uuid";
+import { query, queryOne, execute, pool } from "../db";
+import { eventBus } from "../events";
+import { requireAuth, AuthContext } from "../auth";
+import rateLimit from "express-rate-limit";
+import { logger } from "../logger";
+import { counter } from "../metrics";
+import * as __algorithms from "../algorithms";
+const { shortestPath, topologicalSort, binarySearch, bipartiteMatching, roundRobin, weightedAverage, percentile, rankBy, consistentHash } = __algorithms as any;
+
+import { transitionKnowledgeBase, KNOWLEDGEBASE_INITIAL } from "../state_machines/knowledge_base";
+
+export const knowledgeBasesRouter = Router();
+
+// CREATE
+knowledgeBasesRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { project_id, name, description, embedding_model, embedding_dimensions, chunk_strategy, chunk_size, chunk_overlap, total_files, total_chunks, last_indexed_at } = req.body;
+    const state = KNOWLEDGEBASE_INITIAL;
+    const sql = `INSERT INTO knowledge_bases (id, project_id, name, description, embedding_model, embedding_dimensions, chunk_strategy, chunk_size, chunk_overlap, total_files, total_chunks, last_indexed_at, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13) RETURNING *`;
+    const rows = await query(sql, [id, project_id, name, description, embedding_model, embedding_dimensions, chunk_strategy, chunk_size, chunk_overlap, total_files, total_chunks, last_indexed_at, state]);
+    counter("entity.created", { entity: "KnowledgeBase" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+knowledgeBasesRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM knowledge_bases WHERE id = $1`, [req.params.id]);
+    if (!row) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.json(row);
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// LIST
+knowledgeBasesRouter.get("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM knowledge_bases ORDER BY created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM knowledge_bases`);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// UPDATE
+knowledgeBasesRouter.put("/:id", requireAuth, async (req: Request, res: Response) => {
+  const fields = { ...req.body };
+  // State machine enforcement
+  if (fields.state !== undefined) {
+    const current = await queryOne<{ state: string }>(`SELECT state FROM knowledge_bases WHERE id = $1`, [req.params.id]);
+    if (!current) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    // Find the trigger for this state transition
+    const trigger = `${current.state}_to_${fields.state}`;
+    const tr = transitionKnowledgeBase(current.state as any, trigger);
+    if (!tr.ok) return res.status(422).json({ error: { code: "INVALID_TRANSITION", message: `Cannot transition from ${current.state} to ${fields.state}` } });
+  }
+  const sets = Object.keys(fields).map((k, i) => `${k} = $${i + 2}`).join(", ");
+  const values = Object.values(fields);
+  const sql = `UPDATE knowledge_bases SET ${sets}, updated_at = NOW() WHERE id = $1 RETURNING *`;
+  const rows = await query(sql, [req.params.id, ...values]);
+  if (rows.length === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+  res.json(rows[0]);
+});
+
+// DELETE
+knowledgeBasesRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM knowledge_bases WHERE id = $1`, [req.params.id]);
+    if (count === 0) return res.status(404).json({ error: { code: "NOT_FOUND", message: "Not found" } });
+    res.status(204).send();
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});
+
+// CAPABILITY: ingest_codebase
+knowledgeBasesRouter.post("/ingest-codebase", requireAuth, async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  try {
+    // sync: eventual — effects applied, events queued via outbox
+    const { file_paths } = req.body;
+
+    // Fetch entities
+    const knowledge_base = await queryOne(`SELECT * FROM knowledge_bases WHERE id = $1`, [req.body.knowledge_base_id || req.params.id]);
+    if (!knowledge_base) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "knowledge_base not found" } });
+    }
+
+    // Preconditions
+    if (!([["empty", "ready", "stale", "error"]].flat().includes(knowledge_base?.state))) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "knowledge_base.state in [\\\"empty\\\", \\\"ready\\\", \\\"stale\\\", \\\"error\\\"]" } });
+    }
+
+    // Effects (applied in declaration order)
+    const __effect_0 = await query(`UPDATE knowledge_bases SET state = $1, updated_at = NOW() WHERE id = $2 RETURNING *`, ["indexing", req.body.knowledge_base_id || req.params.id]);
+    if (!__effect_0 || __effect_0.length === 0) {
+      throw new Error("Effect failed: knowledge_base.state = \"indexing\"");
+    }
+
+    // Emit events
+    await eventBus.publish("CodebaseIngestionStarted", { knowledge_base_id: knowledge_base?.id, timestamp: new Date().toISOString(), actor_id: auth.actor_id }, "KnowledgeBaseService", auth.trace_id);
+
+    res.json({ ok: true, action: "ingest_codebase", entity: knowledge_base });
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  }
+});
+
+// CAPABILITY: index_file
+knowledgeBasesRouter.post("/index-file", requireAuth, async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  try {
+    // sync: eventual — effects applied, events queued via outbox
+    const { file_path } = req.body;
+
+    // Fetch entities
+    const knowledge_base = await queryOne(`SELECT * FROM knowledge_bases WHERE id = $1`, [req.body.knowledge_base_id || req.params.id]);
+    if (!knowledge_base) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "knowledge_base not found" } });
+    }
+
+    // Preconditions
+    if (!([["indexing", "ready", "reindexing"]].flat().includes(knowledge_base?.state))) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "knowledge_base.state in [\\\"indexing\\\", \\\"ready\\\", \\\"reindexing\\\"]" } });
+    }
+    if (!(file_path?.length >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "file_path.length >= 1" } });
+    }
+
+    // Emit events
+    await eventBus.publish("FileIndexed", { knowledge_base_id: knowledge_base?.id, timestamp: new Date().toISOString(), actor_id: auth.actor_id }, "KnowledgeBaseService", auth.trace_id);
+
+    res.json({ ok: true, action: "index_file", entity: knowledge_base });
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  }
+});
+
+// CAPABILITY: retrieve_context
+knowledgeBasesRouter.post("/retrieve-context", requireAuth, async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  try {
+    // sync: eventual — effects applied, events queued via outbox
+    const { query, limit } = req.body;
+
+    // Fetch entities
+    const knowledge_base = await queryOne(`SELECT * FROM knowledge_bases WHERE id = $1`, [req.body.knowledge_base_id || req.params.id]);
+    if (!knowledge_base) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "knowledge_base not found" } });
+    }
+
+    // Preconditions
+    if (!(knowledge_base?.state === "ready")) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "knowledge_base.state == \\\"ready\\\"" } });
+    }
+    if (!(query?.length >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "query.length >= 1" } });
+    }
+    if (!(limit >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "limit >= 1" } });
+    }
+    if (!(limit <= 100)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "limit <= 100" } });
+    }
+
+    res.json({ ok: true, action: "retrieve_context", entity: knowledge_base });
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  }
+});
+
+// CAPABILITY: semantic_search
+knowledgeBasesRouter.post("/semantic-search", requireAuth, async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  try {
+    // sync: eventual — effects applied, events queued via outbox
+    const { query, filters, limit } = req.body;
+
+    // Fetch entities
+    const knowledge_base = await queryOne(`SELECT * FROM knowledge_bases WHERE id = $1`, [req.body.knowledge_base_id || req.params.id]);
+    if (!knowledge_base) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "knowledge_base not found" } });
+    }
+
+    // Preconditions
+    if (!(knowledge_base?.state === "ready")) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "knowledge_base.state == \\\"ready\\\"" } });
+    }
+    if (!(query?.length >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "query.length >= 1" } });
+    }
+    if (!(limit >= 1)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "limit >= 1" } });
+    }
+    if (!(limit <= 200)) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "limit <= 200" } });
+    }
+
+    res.json({ ok: true, action: "semantic_search", entity: knowledge_base });
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  }
+});
+
+// RELATION: files (has_many CodeFile)
+knowledgeBasesRouter.get("/:id/files", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const page = parseInt(req.query.page as string) || 1;
+    const pageSize = Math.min(parseInt(req.query.page_size as string) || 50, 100);
+    const offset = (page - 1) * pageSize;
+    const rows = await query(`SELECT * FROM code_files WHERE knowledge_base_id = $1 ORDER BY created_at DESC LIMIT $2 OFFSET $3`, [req.params.id, pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM code_files WHERE knowledge_base_id = $1`, [req.params.id]);
+    res.json({ items: rows, total: parseInt(count), page, page_size: pageSize });
+  } catch (e: any) {
+    res.status(500).json({ error: { code: "DB_ERROR", message: e.message } });
+  }
+});