bonecode 1.0.0

package/bone/output/workspace/src/metrics.ts

@@ -0,0 +1,75 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Implements spec/10 §4 (Telemetry Hooks)
+
+interface Counter {
+  type: "counter";
+  value: number;
+  labels: Record<string, string>;
+}
+
+interface Histogram {
+  type: "histogram";
+  values: number[];
+  labels: Record<string, string>;
+}
+
+interface Gauge {
+  type: "gauge";
+  value: number;
+  labels: Record<string, string>;
+}
+
+type Metric = Counter | Histogram | Gauge;
+
+const metrics: Map<string, Metric> = new Map();
+
+function key(name: string, labels: Record<string, string>): string {
+  const parts = Object.keys(labels).sort().map(k => `${k}="${labels[k]}"`);
+  return parts.length > 0 ? `${name}{${parts.join(",")}}` : name;
+}
+
+export function counter(name: string, labels: Record<string, string> = {}): void {
+  const k = key(name, labels);
+  const existing = metrics.get(k);
+  if (existing && existing.type === "counter") {
+    existing.value++;
+  } else {
+    metrics.set(k, { type: "counter", value: 1, labels });
+  }
+}
+
+export function histogram(name: string, value: number, labels: Record<string, string> = {}): void {
+  const k = key(name, labels);
+  const existing = metrics.get(k);
+  if (existing && existing.type === "histogram") {
+    existing.values.push(value);
+  } else {
+    metrics.set(k, { type: "histogram", values: [value], labels });
+  }
+}
+
+export function gauge(name: string, value: number, labels: Record<string, string> = {}): void {
+  const k = key(name, labels);
+  metrics.set(k, { type: "gauge", value, labels });
+}
+
+export function dump(): string {
+  const lines: string[] = [];
+  for (const [k, m] of metrics.entries()) {
+    if (m.type === "counter" || m.type === "gauge") {
+      lines.push(`${k} ${m.value}`);
+    } else {
+      const sum = m.values.reduce((a, b) => a + b, 0);
+      const count = m.values.length;
+      const avg = count > 0 ? sum / count : 0;
+      lines.push(`${k}_count ${count}`);
+      lines.push(`${k}_sum ${sum}`);
+      lines.push(`${k}_avg ${avg.toFixed(2)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function reset(): void {
+  metrics.clear();
+}

package/bone/output/workspace/src/migrate.ts

@@ -0,0 +1,220 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+require("dotenv").config();
+import { pool } from "./db";
+
+async function migrate() {
+  console.log("Running migrations...");
+  const client = await pool.connect();
+  try {
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: WorkspaceStore
+
+CREATE TABLE IF NOT EXISTS workspaces (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  project_id UUID NOT NULL,
+  root_path VARCHAR NOT NULL,
+  git_remote VARCHAR NOT NULL,
+  git_branch VARCHAR NOT NULL,
+  git_commit VARCHAR NOT NULL,
+  is_dirty BOOLEAN NOT NULL,
+  file_count BIGINT NOT NULL,
+  total_size_bytes BIGINT NOT NULL,
+  config JSONB NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_workspaces_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_workspaces_updated_at
+  BEFORE UPDATE ON workspaces
+  FOR EACH ROW
+  EXECUTE FUNCTION update_workspaces_updated_at();
+`);
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: CodebaseStore
+
+CREATE TABLE IF NOT EXISTS codebases (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  workspace_id UUID NOT NULL,
+  project_id UUID NOT NULL,
+  primary_language VARCHAR NOT NULL,
+  languages JSONB NOT NULL,
+  framework VARCHAR NOT NULL,
+  build_tool VARCHAR NOT NULL,
+  test_framework VARCHAR NOT NULL,
+  entry_points JSONB NOT NULL,
+  dependencies JSONB NOT NULL,
+  analysis_version VARCHAR NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_codebases_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_codebases_updated_at
+  BEFORE UPDATE ON codebases
+  FOR EACH ROW
+  EXECUTE FUNCTION update_codebases_updated_at();
+`);
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: SnapshotStore
+
+CREATE TABLE IF NOT EXISTS snapshots (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  session_id UUID NOT NULL,
+  project_id UUID NOT NULL,
+  workspace_id UUID NOT NULL,
+  git_hash VARCHAR NOT NULL,
+  message_id UUID NOT NULL,
+  part_id UUID NOT NULL,
+  diff_summary JSONB NOT NULL,
+  files_changed BIGINT NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_snapshots_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_snapshots_updated_at
+  BEFORE UPDATE ON snapshots
+  FOR EACH ROW
+  EXECUTE FUNCTION update_snapshots_updated_at();
+`);
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: WorkspaceStore
+
+CREATE TABLE IF NOT EXISTS workspaces (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  project_id UUID NOT NULL,
+  root_path VARCHAR NOT NULL,
+  git_remote VARCHAR NOT NULL,
+  git_branch VARCHAR NOT NULL,
+  git_commit VARCHAR NOT NULL,
+  is_dirty BOOLEAN NOT NULL,
+  file_count BIGINT NOT NULL,
+  total_size_bytes BIGINT NOT NULL,
+  config JSONB NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_workspaces_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_workspaces_updated_at
+  BEFORE UPDATE ON workspaces
+  FOR EACH ROW
+  EXECUTE FUNCTION update_workspaces_updated_at();
+`);
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: CodebaseStore
+
+CREATE TABLE IF NOT EXISTS codebases (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  workspace_id UUID NOT NULL,
+  project_id UUID NOT NULL,
+  primary_language VARCHAR NOT NULL,
+  languages JSONB NOT NULL,
+  framework VARCHAR NOT NULL,
+  build_tool VARCHAR NOT NULL,
+  test_framework VARCHAR NOT NULL,
+  entry_points JSONB NOT NULL,
+  dependencies JSONB NOT NULL,
+  analysis_version VARCHAR NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_codebases_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_codebases_updated_at
+  BEFORE UPDATE ON codebases
+  FOR EACH ROW
+  EXECUTE FUNCTION update_codebases_updated_at();
+`);
+    await client.query(`-- Generated by BoneScript compiler. DO NOT EDIT.
+-- Source: be6ae747864f48c9
+-- Module: SnapshotStore
+
+CREATE TABLE IF NOT EXISTS snapshots (
+  id UUID NOT NULL DEFAULT gen_random_uuid() PRIMARY KEY,
+  session_id UUID NOT NULL,
+  project_id UUID NOT NULL,
+  workspace_id UUID NOT NULL,
+  git_hash VARCHAR NOT NULL,
+  message_id UUID NOT NULL,
+  part_id UUID NOT NULL,
+  diff_summary JSONB NOT NULL,
+  files_changed BIGINT NOT NULL,
+  state VARCHAR NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+
+CREATE OR REPLACE FUNCTION update_snapshots_updated_at()
+RETURNS TRIGGER AS \$\$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+\$\$ LANGUAGE plpgsql;
+
+CREATE TRIGGER trg_snapshots_updated_at
+  BEFORE UPDATE ON snapshots
+  FOR EACH ROW
+  EXECUTE FUNCTION update_snapshots_updated_at();
+`);
+    console.log("Migrations complete.");
+  } finally {
+    client.release();
+    await pool.end();
+  }
+}
+
+migrate().catch(e => { console.error(e); process.exit(1); });

package/bone/output/workspace/src/migration_diff.ts

@@ -0,0 +1,108 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Migration diff utility — compares two IR snapshots and produces ALTER statements.
+
+import * as fs from "fs";
+
+interface Field {
+  name: string;
+  type: string;
+  nullable: boolean;
+}
+
+interface Model {
+  name: string;
+  fields: Field[];
+  primary_key: string;
+}
+
+export function diffModels(oldModels: Model[], newModels: Model[]): string[] {
+  const statements: string[] = [];
+  const oldByName = new Map(oldModels.map(m => [m.name, m]));
+  const newByName = new Map(newModels.map(m => [m.name, m]));
+
+  // New tables
+  for (const [name, model] of newByName) {
+    if (!oldByName.has(name)) {
+      const tableName = toSnake(name) + "s";
+      statements.push(`-- New table: ${tableName}`);
+      statements.push(`-- (Generated by previous migration)`);
+    }
+  }
+
+  // Removed tables (warn but don't auto-drop)
+  for (const [name] of oldByName) {
+    if (!newByName.has(name)) {
+      const tableName = toSnake(name) + "s";
+      statements.push(`-- WARNING: Table ${tableName} no longer in schema. Manual DROP required.`);
+    }
+  }
+
+  // Modified tables
+  for (const [name, newModel] of newByName) {
+    const oldModel = oldByName.get(name);
+    if (!oldModel) continue;
+
+    const tableName = toSnake(name) + "s";
+    const oldFields = new Map(oldModel.fields.map(f => [f.name, f]));
+    const newFields = new Map(newModel.fields.map(f => [f.name, f]));
+
+    // New columns (backward-compatible)
+    for (const [fname, field] of newFields) {
+      if (!oldFields.has(fname)) {
+        const sqlType = mapType(field.type);
+        const nullability = field.nullable ? "" : " NOT NULL DEFAULT (CASE WHEN false THEN NULL ELSE NULL END)";
+        statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${fname} ${sqlType}${nullability};`);
+      }
+    }
+
+    // Removed columns (NOT auto-dropped — backward compat)
+    for (const [fname] of oldFields) {
+      if (!newFields.has(fname)) {
+        statements.push(`-- WARNING: Column ${tableName}.${fname} removed from schema. Run manually: ALTER TABLE ${tableName} DROP COLUMN ${fname};`);
+      }
+    }
+
+    // Type changes
+    for (const [fname, newField] of newFields) {
+      const oldField = oldFields.get(fname);
+      if (!oldField) continue;
+      if (oldField.type !== newField.type) {
+        const sqlType = mapType(newField.type);
+        statements.push(`ALTER TABLE ${tableName} ALTER COLUMN ${fname} TYPE ${sqlType};`);
+      }
+    }
+  }
+
+  return statements;
+}
+
+function toSnake(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+function mapType(t: string): string {
+  const map: Record<string, string> = {
+    string: "VARCHAR", uint: "BIGINT", int: "BIGINT", float: "DOUBLE PRECISION",
+    bool: "BOOLEAN", timestamp: "TIMESTAMPTZ", uuid: "UUID", bytes: "BYTEA", json: "JSONB",
+  };
+  return map[t] || "JSONB";
+}
+
+if (require.main === module) {
+  const oldFile = process.argv[2];
+  const newFile = process.argv[3];
+  if (!oldFile || !newFile) {
+    console.error("Usage: node migration-diff.js <old-ir.json> <new-ir.json>");
+    process.exit(1);
+  }
+  const oldIR = JSON.parse(fs.readFileSync(oldFile, "utf-8"));
+  const newIR = JSON.parse(fs.readFileSync(newFile, "utf-8"));
+
+  const oldModels: Model[] = [];
+  const newModels: Model[] = [];
+  for (const sys of oldIR) for (const mod of sys.modules) for (const m of mod.models) oldModels.push(m);
+  for (const sys of newIR) for (const mod of sys.modules) for (const m of mod.models) newModels.push(m);
+
+  const diff = diffModels(oldModels, newModels);
+  console.log(diff.join("\n"));
+}

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

@@ -0,0 +1,73 @@
+// 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 WorkspaceInitialized
+export async function notifyWorkspaceInitialized(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "WorkspaceInitialized notification",
+    body: `<p>Event <strong>WorkspaceInitialized</strong> occurred.</p><pre>${JSON.stringify(event.payload, null, 2)}</pre>`,
+  });
+}
+
+// Handler for SnapshotCreated
+export async function notifySnapshotCreated(event: SystemEvent, recipientEmail: string): Promise<void> {
+  await sendEmail({
+    to: recipientEmail,
+    subject: "SnapshotCreated notification",
+    body: `<p>Event <strong>SnapshotCreated</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("WorkspaceInitialized", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifyWorkspaceInitialized(event, recipientEmail);
+  // });
+  // eventBus.subscribe("SnapshotCreated", async (event: SystemEvent) => {
+  //   const recipientEmail = await lookupRecipient(event);
+  //   await notifySnapshotCreated(event, recipientEmail);
+  // });
+}

package/bone/output/workspace/src/routes/codebase.ts

@@ -0,0 +1,87 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: CodebaseService
+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 { transitionCodebase, CODEBASE_INITIAL } from "../state_machines/codebase";
+
+export const codebasesRouter = Router();
+
+// CREATE
+codebasesRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { workspace_id, project_id, primary_language, languages, framework, build_tool, test_framework, entry_points, dependencies, analysis_version } = req.body;
+    const state = CODEBASE_INITIAL;
+    const sql = `INSERT INTO codebases (id, workspace_id, project_id, primary_language, languages, framework, build_tool, test_framework, entry_points, dependencies, analysis_version, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12) RETURNING *`;
+    const rows = await query(sql, [id, workspace_id, project_id, primary_language, languages, framework, build_tool, test_framework, entry_points, dependencies, analysis_version, state]);
+    counter("entity.created", { entity: "Codebase" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+codebasesRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM codebases 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
+codebasesRouter.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 codebases.*, row_to_json(workspace.*) as workspace FROM codebases LEFT JOIN workspaces workspace ON codebases.workspace_id = workspace.id ORDER BY codebases.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM codebases`);
+    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
+codebasesRouter.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 codebases 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 = transitionCodebase(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 codebases 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
+codebasesRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM codebases 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/workspace/src/routes/snapshot.ts

@@ -0,0 +1,127 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Service: SnapshotService
+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 { transitionSnapshot, SNAPSHOT_INITIAL } from "../state_machines/snapshot";
+
+export const snapshotsRouter = Router();
+
+// CREATE
+snapshotsRouter.post("/", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const id = uuid();
+    const { session_id, project_id, workspace_id, git_hash, message_id, part_id, diff_summary, files_changed } = req.body;
+    const state = SNAPSHOT_INITIAL;
+    const sql = `INSERT INTO snapshots (id, session_id, project_id, workspace_id, git_hash, message_id, part_id, diff_summary, files_changed, state) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10) RETURNING *`;
+    const rows = await query(sql, [id, session_id, project_id, workspace_id, git_hash, message_id, part_id, diff_summary, files_changed, state]);
+    counter("entity.created", { entity: "Snapshot" });
+    res.status(201).json(rows[0]);
+  } catch (e: any) {
+    res.status(400).json({ error: { code: "CREATE_FAILED", message: e.message } });
+  }
+});
+
+// READ
+snapshotsRouter.get("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const row = await queryOne(`SELECT * FROM snapshots 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
+snapshotsRouter.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 snapshots.*, row_to_json(workspace.*) as workspace FROM snapshots LEFT JOIN workspaces workspace ON snapshots.workspace_id = workspace.id ORDER BY snapshots.created_at DESC LIMIT $1 OFFSET $2`, [pageSize, offset]);
+    const [{ count }] = await query(`SELECT COUNT(*) as count FROM snapshots`);
+    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
+snapshotsRouter.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 snapshots 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 = transitionSnapshot(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 snapshots 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
+snapshotsRouter.delete("/:id", requireAuth, async (req: Request, res: Response) => {
+  try {
+    const count = await execute(`DELETE FROM snapshots 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: revert_to_snapshot [transactional]
+snapshotsRouter.post("/revert-to-snapshot", requireAuth, async (req: Request, res: Response) => {
+  const auth: AuthContext = (req as any).auth;
+  const __client = await pool.connect();
+  try {
+    await __client.query("BEGIN");
+    // Fetch entities
+    const workspace = await queryOne(`SELECT * FROM workspaces WHERE id = $1`, [req.body.workspace_id || req.params.id]);
+    if (!workspace) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "workspace not found" } });
+    }
+    const snapshot = await queryOne(`SELECT * FROM snapshots WHERE id = $1`, [req.body.snapshot_id || req.params.id]);
+    if (!snapshot) {
+      return res.status(404).json({ error: { code: "NOT_FOUND", message: "snapshot not found" } });
+    }
+
+    // Preconditions
+    if (!([["ready", "dirty"]].flat().includes(workspace?.state))) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "workspace.state in [\\\"ready\\\", \\\"dirty\\\"]" } });
+    }
+    if (!(snapshot?.state === "committed")) {
+      return res.status(422).json({ error: { code: "PRECONDITION_FAILED", message: "snapshot.state == \\\"committed\\\"" } });
+    }
+
+    // Effects (applied in declaration order)
+    const __effect_0 = await query(`UPDATE workspaces SET is_dirty = $1, updated_at = NOW() WHERE id = $2 RETURNING *`, [false, req.body.workspace_id || req.params.id]);
+    if (!__effect_0 || __effect_0.length === 0) {
+      throw new Error("Effect failed: workspace.is_dirty = false");
+    }
+
+    res.json({ ok: true, action: "revert_to_snapshot", entity: workspace });
+    await __client.query("COMMIT");
+  } catch (e: any) {
+    await __client.query("ROLLBACK");
+    res.status(400).json({ error: { code: "CAPABILITY_FAILED", message: e.message } });
+  } finally {
+    __client.release();
+  }
+});