bonecode 1.0.0

package/bone/output/agent/src/tests.ts

@@ -0,0 +1,362 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// Regression tests derived from capability declarations.
+// Run: npx ts-node src/tests.ts
+
+import * as http from "http";
+
+const BASE_URL = process.env.TEST_BASE_URL || "http://localhost:3000";
+const AUTH_TOKEN = process.env.TEST_AUTH_TOKEN || "";
+
+let passed = 0;
+let failed = 0;
+
+async function request(method: string, path: string, body?: any): Promise<{ status: number; data: any }> {
+  const url = new URL(path, BASE_URL);
+  const res = await fetch(url.toString(), {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...(AUTH_TOKEN ? { "Authorization": `Bearer ${AUTH_TOKEN}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  return { status: res.status, data };
+}
+
+async function test(name: string, fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (e: any) {
+    console.log(`  ✗ ${name}: ${e.message}`);
+    failed++;
+  }
+}
+
+function assert(condition: boolean, message: string): void {
+  if (!condition) throw new Error(message);
+}
+
+(async () => {
+// ─── AgentInstanceService Tests ─────────────────────────────────────────────────────
+
+console.log("\nAgentInstanceService — CRUD");
+
+let __agent_instance_id: string;
+
+await test("POST /agent_instances — creates entity", async () => {
+  const { status, data } = await request("POST", "/agent_instances", {"session_id":"00000000-0000-0000-0000-000000000001","model_id":"test_value","provider_id":"test_value","system_prompt":null,"temperature":null,"max_tokens":null,"context_window_used":1,"context_window_max":1,"total_cost_usd":1,"total_tokens_in":1,"total_tokens_out":1,"config":{}});
+  assert(status === 201, `Expected 201, got ${status}: ${JSON.stringify(data)}`);
+  assert(data.id, "Response must have id");
+  __agent_instance_id = data.id;
+});
+
+await test("GET /agent_instances/:id — reads entity", async () => {
+  const { status, data } = await request("GET", `/agent_instances/${__agent_instance_id}`);
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(data.id === __agent_instance_id, "ID must match");
+});
+
+await test("GET /agent_instances — lists entities", async () => {
+  const { status, data } = await request("GET", "/agent_instances");
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(Array.isArray(data.items), "Response must have items array");
+  assert(typeof data.total === "number", "Response must have total");
+});
+
+await test("GET /agent_instances — rejects unauthenticated", async () => {
+  const res = await fetch(`${BASE_URL}/agent_instances`);
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+await test("POST /agent_instances/complete-agent — capability executes", async () => {
+  const { status, data } = await request("POST", "/agent_instances/complete-agent", {
+    agent_instance_id: __agent_instance_id,
+  });
+  // Capability may return 200 (success) or 422 (precondition failed) — both are valid
+  assert([200, 422].includes(status), `Expected 200 or 422, got ${status}: ${JSON.stringify(data)}`);
+});
+
+await test("POST /agent_instances/complete-agent — returns 401 without auth", async () => {
+  const res = await fetch(`${BASE_URL}/agent_instances/complete-agent`, { method: "POST" });
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+await test("POST /agent_instances/fail-agent — capability executes", async () => {
+  const { status, data } = await request("POST", "/agent_instances/fail-agent", {
+    agent_instance_id: __agent_instance_id,
+  });
+  // Capability may return 200 (success) or 422 (precondition failed) — both are valid
+  assert([200, 422].includes(status), `Expected 200 or 422, got ${status}: ${JSON.stringify(data)}`);
+});
+
+await test("POST /agent_instances/fail-agent — returns 401 without auth", async () => {
+  const res = await fetch(`${BASE_URL}/agent_instances/fail-agent`, { method: "POST" });
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+await test("POST /agent_instances/request-tool-call — capability executes", async () => {
+  const { status, data } = await request("POST", "/agent_instances/request-tool-call", {
+    agent_instance_id: __agent_instance_id,
+  });
+  // Capability may return 200 (success) or 422 (precondition failed) — both are valid
+  assert([200, 422].includes(status), `Expected 200 or 422, got ${status}: ${JSON.stringify(data)}`);
+});
+
+await test("POST /agent_instances/request-tool-call — returns 401 without auth", async () => {
+  const res = await fetch(`${BASE_URL}/agent_instances/request-tool-call`, { method: "POST" });
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+// State machine: AgentInstance
+await test("PUT /agent_instances/:id — rejects invalid state transition", async () => {
+  const { status, data } = await request("PUT", `/agent_instances/${__agent_instance_id}`, {
+    state: "__invalid_state__",
+  });
+  assert(status === 422, `Expected 422 for invalid transition, got ${status}`);
+  assert(data.error?.code === "INVALID_TRANSITION", "Error code must be INVALID_TRANSITION");
+});
+
+await test("DELETE /agent_instances/:id — deletes entity", async () => {
+  const { status } = await request("DELETE", `/agent_instances/${__agent_instance_id}`);
+  assert(status === 204, `Expected 204, got ${status}`);
+});
+
+await test("GET /agent_instances/:id — returns 404 after delete", async () => {
+  const { status } = await request("GET", `/agent_instances/${__agent_instance_id}`);
+  assert(status === 404, `Expected 404, got ${status}`);
+});
+
+// ─── TaskService Tests ─────────────────────────────────────────────────────
+
+console.log("\nTaskService — CRUD");
+
+let __task_id: string;
+
+await test("POST /tasks — creates entity", async () => {
+  const { status, data } = await request("POST", "/tasks", {"agent_id":"00000000-0000-0000-0000-000000000001","session_id":"00000000-0000-0000-0000-000000000001","description":"test_value","priority":1,"result":null,"error":null});
+  assert(status === 201, `Expected 201, got ${status}: ${JSON.stringify(data)}`);
+  assert(data.id, "Response must have id");
+  __task_id = data.id;
+});
+
+await test("GET /tasks/:id — reads entity", async () => {
+  const { status, data } = await request("GET", `/tasks/${__task_id}`);
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(data.id === __task_id, "ID must match");
+});
+
+await test("GET /tasks — lists entities", async () => {
+  const { status, data } = await request("GET", "/tasks");
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(Array.isArray(data.items), "Response must have items array");
+  assert(typeof data.total === "number", "Response must have total");
+});
+
+await test("GET /tasks — rejects unauthenticated", async () => {
+  const res = await fetch(`${BASE_URL}/tasks`);
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+// State machine: Task
+await test("PUT /tasks/:id — rejects invalid state transition", async () => {
+  const { status, data } = await request("PUT", `/tasks/${__task_id}`, {
+    state: "__invalid_state__",
+  });
+  assert(status === 422, `Expected 422 for invalid transition, got ${status}`);
+  assert(data.error?.code === "INVALID_TRANSITION", "Error code must be INVALID_TRANSITION");
+});
+
+await test("DELETE /tasks/:id — deletes entity", async () => {
+  const { status } = await request("DELETE", `/tasks/${__task_id}`);
+  assert(status === 204, `Expected 204, got ${status}`);
+});
+
+await test("GET /tasks/:id — returns 404 after delete", async () => {
+  const { status } = await request("GET", `/tasks/${__task_id}`);
+  assert(status === 404, `Expected 404, got ${status}`);
+});
+
+// ─── PlanService Tests ─────────────────────────────────────────────────────
+
+console.log("\nPlanService — CRUD");
+
+let __plan_id: string;
+
+await test("POST /plans — creates entity", async () => {
+  const { status, data } = await request("POST", "/plans", {"session_id":"00000000-0000-0000-0000-000000000001","agent_id":"00000000-0000-0000-0000-000000000001","task_id":"00000000-0000-0000-0000-000000000001","steps":{},"rationale":null,"estimated_tokens":null});
+  assert(status === 201, `Expected 201, got ${status}: ${JSON.stringify(data)}`);
+  assert(data.id, "Response must have id");
+  __plan_id = data.id;
+});
+
+await test("GET /plans/:id — reads entity", async () => {
+  const { status, data } = await request("GET", `/plans/${__plan_id}`);
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(data.id === __plan_id, "ID must match");
+});
+
+await test("GET /plans — lists entities", async () => {
+  const { status, data } = await request("GET", "/plans");
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(Array.isArray(data.items), "Response must have items array");
+  assert(typeof data.total === "number", "Response must have total");
+});
+
+await test("GET /plans — rejects unauthenticated", async () => {
+  const res = await fetch(`${BASE_URL}/plans`);
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+// State machine: Plan
+await test("PUT /plans/:id — rejects invalid state transition", async () => {
+  const { status, data } = await request("PUT", `/plans/${__plan_id}`, {
+    state: "__invalid_state__",
+  });
+  assert(status === 422, `Expected 422 for invalid transition, got ${status}`);
+  assert(data.error?.code === "INVALID_TRANSITION", "Error code must be INVALID_TRANSITION");
+});
+
+await test("DELETE /plans/:id — deletes entity", async () => {
+  const { status } = await request("DELETE", `/plans/${__plan_id}`);
+  assert(status === 204, `Expected 204, got ${status}`);
+});
+
+await test("GET /plans/:id — returns 404 after delete", async () => {
+  const { status } = await request("GET", `/plans/${__plan_id}`);
+  assert(status === 404, `Expected 404, got ${status}`);
+});
+
+// ─── BuildStepService Tests ─────────────────────────────────────────────────────
+
+console.log("\nBuildStepService — CRUD");
+
+let __build_step_id: string;
+
+await test("POST /build_steps — creates entity", async () => {
+  const { status, data } = await request("POST", "/build_steps", {"task_id":"00000000-0000-0000-0000-000000000001","agent_id":"00000000-0000-0000-0000-000000000001","session_id":"00000000-0000-0000-0000-000000000001","step_type":"test_value","description":"test_value","file_path":null,"diff":null,"result":null,"error":null,"order_index":1});
+  assert(status === 201, `Expected 201, got ${status}: ${JSON.stringify(data)}`);
+  assert(data.id, "Response must have id");
+  __build_step_id = data.id;
+});
+
+await test("GET /build_steps/:id — reads entity", async () => {
+  const { status, data } = await request("GET", `/build_steps/${__build_step_id}`);
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(data.id === __build_step_id, "ID must match");
+});
+
+await test("GET /build_steps — lists entities", async () => {
+  const { status, data } = await request("GET", "/build_steps");
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(Array.isArray(data.items), "Response must have items array");
+  assert(typeof data.total === "number", "Response must have total");
+});
+
+await test("GET /build_steps — rejects unauthenticated", async () => {
+  const res = await fetch(`${BASE_URL}/build_steps`);
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+// State machine: BuildStep
+await test("PUT /build_steps/:id — rejects invalid state transition", async () => {
+  const { status, data } = await request("PUT", `/build_steps/${__build_step_id}`, {
+    state: "__invalid_state__",
+  });
+  assert(status === 422, `Expected 422 for invalid transition, got ${status}`);
+  assert(data.error?.code === "INVALID_TRANSITION", "Error code must be INVALID_TRANSITION");
+});
+
+await test("DELETE /build_steps/:id — deletes entity", async () => {
+  const { status } = await request("DELETE", `/build_steps/${__build_step_id}`);
+  assert(status === 204, `Expected 204, got ${status}`);
+});
+
+await test("GET /build_steps/:id — returns 404 after delete", async () => {
+  const { status } = await request("GET", `/build_steps/${__build_step_id}`);
+  assert(status === 404, `Expected 404, got ${status}`);
+});
+
+// ─── ToolCallService Tests ─────────────────────────────────────────────────────
+
+console.log("\nToolCallService — CRUD");
+
+let __tool_call_id: string;
+
+await test("POST /tool_calls — creates entity", async () => {
+  const { status, data } = await request("POST", "/tool_calls", {"session_id":"00000000-0000-0000-0000-000000000001","agent_id":"00000000-0000-0000-0000-000000000001","build_step_id":null,"tool_name":"test_value","tool_input":{},"tool_output":null,"error":null,"duration_ms":null,"permission_decision":null});
+  assert(status === 201, `Expected 201, got ${status}: ${JSON.stringify(data)}`);
+  assert(data.id, "Response must have id");
+  __tool_call_id = data.id;
+});
+
+await test("GET /tool_calls/:id — reads entity", async () => {
+  const { status, data } = await request("GET", `/tool_calls/${__tool_call_id}`);
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(data.id === __tool_call_id, "ID must match");
+});
+
+await test("GET /tool_calls — lists entities", async () => {
+  const { status, data } = await request("GET", "/tool_calls");
+  assert(status === 200, `Expected 200, got ${status}`);
+  assert(Array.isArray(data.items), "Response must have items array");
+  assert(typeof data.total === "number", "Response must have total");
+});
+
+await test("GET /tool_calls — rejects unauthenticated", async () => {
+  const res = await fetch(`${BASE_URL}/tool_calls`);
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+await test("POST /tool_calls/complete-tool-call — capability executes", async () => {
+  const { status, data } = await request("POST", "/tool_calls/complete-tool-call", {
+    tool_call_id: __tool_call_id,
+  });
+  // Capability may return 200 (success) or 422 (precondition failed) — both are valid
+  assert([200, 422].includes(status), `Expected 200 or 422, got ${status}: ${JSON.stringify(data)}`);
+});
+
+await test("POST /tool_calls/complete-tool-call — returns 401 without auth", async () => {
+  const res = await fetch(`${BASE_URL}/tool_calls/complete-tool-call`, { method: "POST" });
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+await test("POST /tool_calls/deny-tool-call — capability executes", async () => {
+  const { status, data } = await request("POST", "/tool_calls/deny-tool-call", {
+    tool_call_id: __tool_call_id,
+  });
+  // Capability may return 200 (success) or 422 (precondition failed) — both are valid
+  assert([200, 422].includes(status), `Expected 200 or 422, got ${status}: ${JSON.stringify(data)}`);
+});
+
+await test("POST /tool_calls/deny-tool-call — returns 401 without auth", async () => {
+  const res = await fetch(`${BASE_URL}/tool_calls/deny-tool-call`, { method: "POST" });
+  assert(res.status === 401, `Expected 401, got ${res.status}`);
+});
+
+// State machine: ToolCall
+await test("PUT /tool_calls/:id — rejects invalid state transition", async () => {
+  const { status, data } = await request("PUT", `/tool_calls/${__tool_call_id}`, {
+    state: "__invalid_state__",
+  });
+  assert(status === 422, `Expected 422 for invalid transition, got ${status}`);
+  assert(data.error?.code === "INVALID_TRANSITION", "Error code must be INVALID_TRANSITION");
+});
+
+await test("DELETE /tool_calls/:id — deletes entity", async () => {
+  const { status } = await request("DELETE", `/tool_calls/${__tool_call_id}`);
+  assert(status === 204, `Expected 204, got ${status}`);
+});
+
+await test("GET /tool_calls/:id — returns 404 after delete", async () => {
+  const { status } = await request("GET", `/tool_calls/${__tool_call_id}`);
+  assert(status === 404, `Expected 404, got ${status}`);
+});
+
+console.log(`\n════════════════════════════════════════`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log("═".repeat(40));
+if (failed > 0) process.exit(1);
+})().catch(e => { console.error(e); process.exit(1); });

package/bone/output/agent/src/websocket.ts

@@ -0,0 +1,201 @@
+// Generated by BoneScript compiler. DO NOT EDIT.
+// WebSocket server for realtime channels
+
+import { WebSocketServer, WebSocket } from "ws";
+import { IncomingMessage, Server } from "http";
+import jwt from "jsonwebtoken";
+import { eventBus } from "./events";
+import { logger } from "./logger";
+
+const JWT_SECRET = process.env.JWT_SECRET || "bonescript-dev-secret-change-in-production";
+
+// Redis pub/sub for multi-instance WebSocket broadcasting
+let redisSub: any = null;
+let redisPub: any = null;
+if (process.env.REDIS_URL) {
+  try {
+    const { createClient } = require("redis");
+    redisSub = createClient({ url: process.env.REDIS_URL });
+    redisPub = createClient({ url: process.env.REDIS_URL });
+    Promise.all([redisSub.connect(), redisPub.connect()]).then(() => {
+      logger.info("redis_connected", { event: "startup" });
+    }).catch((e: any) => {
+      logger.error("redis_connect_failed", { event: "startup", metadata: { error: e.message } });
+      redisSub = null; redisPub = null;
+    });
+  } catch { redisSub = null; redisPub = null; }
+}
+interface Client {
+  socket: WebSocket;
+  user_id: string;
+  channel: string;
+  topics: Set<string>;
+}
+
+const clients: Map<string, Set<Client>> = new Map();
+
+const CHANNELS: Record<string, { ordering: string; persistence: string; max_size: number }> = {
+  "agent_events": {
+    ordering: "causal",
+    persistence: "last_500",
+    max_size: 50000,
+  },
+  "tool_permission_requests": {
+    ordering: "fifo",
+    persistence: "last_50",
+    max_size: 10000,
+  },
+};
+
+const messageBuffers: Map<string, any[]> = new Map();
+
+function getBuffer(channel: string): any[] {
+  const buf = messageBuffers.get(channel);
+  if (buf) return buf;
+  const fresh: any[] = [];
+  messageBuffers.set(channel, fresh);
+  return fresh;
+}
+
+function persistMessage(channel: string, msg: any) {
+  const cfg = CHANNELS[channel];
+  if (!cfg || cfg.persistence === "none") return;
+  const buf = getBuffer(channel);
+  buf.push(msg);
+
+  // Honor persistence config (last_N, full)
+  const match = cfg.persistence.match(/^last_(\d+)$/);
+  if (match) {
+    const limit = parseInt(match[1], 10);
+    while (buf.length > limit) buf.shift();
+  } else if (buf.length > cfg.max_size) {
+    buf.shift();
+  }
+}
+
+export function setupWebSocketServer(httpServer: Server): WebSocketServer {
+  const wss = new WebSocketServer({ server: httpServer, path: "/ws" });
+
+  wss.on("connection", (socket: WebSocket, req: IncomingMessage) => {
+    const url = new URL(req.url || "/", `http://${req.headers.host}`);
+    const channel = url.searchParams.get("channel") || "";
+    const token = url.searchParams.get("token") || "";
+
+    if (!CHANNELS[channel]) {
+      socket.send(JSON.stringify({ type: "error", message: "Unknown channel: " + channel }));
+      socket.close();
+      return;
+    }
+
+    let userId: string;
+    try {
+      const decoded = jwt.verify(token, JWT_SECRET) as { sub: string };
+      userId = decoded.sub;
+    } catch {
+      socket.send(JSON.stringify({ type: "error", message: "Authentication failed" }));
+      socket.close();
+      return;
+    }
+
+    const client: Client = { socket, user_id: userId, channel, topics: new Set() };
+    const set = clients.get(channel) || new Set();
+    set.add(client);
+    clients.set(channel, set);
+
+    console.log(`[ws] User ${userId} connected to ${channel} (${set.size} active)`);
+
+    // Send buffered history
+    const history = messageBuffers.get(channel) || [];
+    for (const msg of history) {
+      socket.send(JSON.stringify(msg));
+    }
+
+    socket.send(JSON.stringify({ type: "connected", channel, history_size: history.length }));
+
+    socket.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+
+        if (msg.type === "subscribe" && msg.topic) {
+          client.topics.add(msg.topic);
+          return;
+        }
+        if (msg.type === "unsubscribe" && msg.topic) {
+          client.topics.delete(msg.topic);
+          return;
+        }
+
+        // Broadcast
+        const broadcast = {
+          type: msg.type || "message",
+          payload: msg.payload || msg,
+          from: userId,
+          timestamp: new Date().toISOString(),
+        };
+
+        persistMessage(channel, broadcast);
+        broadcastToChannel(channel, broadcast, client);
+      } catch (e: any) {
+        socket.send(JSON.stringify({ type: "error", message: e.message }));
+      }
+    });
+
+    socket.on("close", () => {
+      const set = clients.get(channel);
+      if (set) set.delete(client);
+      console.log(`[ws] User ${userId} disconnected from ${channel}`);
+    });
+
+    // Heartbeat
+    const heartbeat = setInterval(() => {
+      if (socket.readyState === WebSocket.OPEN) {
+        socket.ping();
+      } else {
+        clearInterval(heartbeat);
+      }
+    }, 30000);
+  });
+
+  // Bridge: forward eventBus events to WebSocket clients
+  // Channel 'agent_events' bridge
+  // Channel 'tool_permission_requests' bridge
+
+  // Subscribe to Redis channels for cross-instance delivery
+  if (redisSub) {
+    redisSub.subscribe("ws:agent_events", (message: string) => {
+      const set = clients.get("agent_events");
+      if (!set) return;
+      for (const client of set) {
+        if (client.socket.readyState === WebSocket.OPEN) client.socket.send(message);
+      }
+    }).catch(() => {});
+    redisSub.subscribe("ws:tool_permission_requests", (message: string) => {
+      const set = clients.get("tool_permission_requests");
+      if (!set) return;
+      for (const client of set) {
+        if (client.socket.readyState === WebSocket.OPEN) client.socket.send(message);
+      }
+    }).catch(() => {});
+  }
+  return wss;
+}
+
+function broadcastToChannel(channel: string, message: any, exclude?: Client) {
+  const set = clients.get(channel);
+  const data = JSON.stringify(message);
+  // Broadcast to local clients
+  if (set) {
+    for (const client of set) {
+      if (client === exclude) continue;
+      if (client.socket.readyState === WebSocket.OPEN) {
+        client.socket.send(data);
+      }
+    }
+  }
+  // Publish to Redis for cross-instance delivery
+  if (redisPub) {
+    redisPub.publish(`ws:${channel}`, data).catch(() => {});
+  }
+}
+
+export { broadcastToChannel };

package/bone/output/agent/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": [
+      "ES2020",
+      "DOM"
+    ],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/bone/output/rag/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.env
+*.log
+.git
+*.bone
+*.bone.map

package/bone/output/rag/.env.example

@@ -0,0 +1,36 @@
+# RAGDomain Environment Variables
+# Copy this file to .env and fill in real values. Never commit .env to source control.
+
+# --- Required in production ---
+# Generate with: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# --- Database ---
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ragdomain
+
+# --- Redis (optional, used by some domain templates) ---
+REDIS_URL=redis://localhost:6379
+
+# --- Server ---
+PORT=3000
+NODE_ENV=development
+
+# --- CORS ---
+# Comma-separated list of allowed origins. Leave empty to disallow all cross-origin requests.
+# Example: ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
+ALLOWED_ORIGINS=
+
+# --- Event delivery mode ---
+# in_process: in-memory, fast, no durability guarantees (default for development)
+# durable: Postgres-backed transactional outbox (recommended for production)
+EVENT_MODE=in_process
+EVENT_WORKER_INTERVAL_MS=1000
+
+# --- Request timeout ---
+REQUEST_TIMEOUT_MS=30000
+
+# --- Notifications ---
+# NOTIFY_PROVIDER=log|resend|sendgrid (default: log)
+NOTIFY_PROVIDER=log
+NOTIFY_API_KEY=
+NOTIFY_FROM_EMAIL=noreply@example.com