@hasna/economy 0.2.41 → 0.2.43

package/dist/server/index.js

@@ -573,6 +573,32 @@ function getDbPath() {
     return process.env["ECONOMY_DB"];
   return join(getDataDir(), "economy.db");
 }
+function isSqliteBusyError(error) {
+  const candidate = error;
+  const code = typeof candidate.code === "string" ? candidate.code : "";
+  const message = typeof candidate.message === "string" ? candidate.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_RECOVERY" || /database is locked|SQLITE_BUSY/i.test(message);
+}
+function retryDelayMs(attempt) {
+  return Math.min(1000, 50 * 2 ** attempt);
+}
+function withSqliteBusyRetry(operation, context) {
+  const maxAttempts = 8;
+  let lastError;
+  for (let attempt = 0;attempt < maxAttempts; attempt++) {
+    try {
+      return operation();
+    } catch (error) {
+      if (!isSqliteBusyError(error))
+        throw error;
+      lastError = error;
+      if (attempt === maxAttempts - 1)
+        break;
+      Bun.sleepSync(retryDelayMs(attempt));
+    }
+  }
+  throw new Error(`SQLite database is locked after ${maxAttempts} attempts while ${context}. Another economy sync/merge may be recovering the database; retry shortly.`, { cause: lastError });
+}
 function openDatabase(dbPath, skipSeed = false) {
   const path = dbPath ?? getDbPath();
   if (path !== ":memory:") {
@@ -580,11 +606,21 @@ function openDatabase(dbPath, skipSeed = false) {
     if (dir && !existsSync(dir))
       mkdirSync(dir, { recursive: true });
   }
-  const db = new Database(path);
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA busy_timeout = 5000");
-  db.exec("PRAGMA foreign_keys = ON");
-  initSchema(db);
+  const db = withSqliteBusyRetry(() => {
+    const opened = new Database(path);
+    try {
+      opened.exec("PRAGMA busy_timeout = 10000");
+      opened.exec("PRAGMA journal_mode = WAL");
+      opened.exec("PRAGMA foreign_keys = ON");
+      initSchema(opened);
+      return opened;
+    } catch (error) {
+      try {
+        opened.close();
+      } catch {}
+      throw error;
+    }
+  }, `opening ${path}`);
   if (!skipSeed) {
     Promise.resolve().then(() => (init_pricing(), exports_pricing)).then(({ ensurePricingSeeded: ensurePricingSeeded2 }) => ensurePricingSeeded2(db)).catch(() => {});
   }
@@ -946,36 +982,50 @@ function querySessions(db, filter = {}) {
     SELECT * FROM sessions ${where} ORDER BY started_at DESC LIMIT ? OFFSET ?
   `).all(...params, limit, offset);
 }
-function queryTopSessions(db, n = 10, agent) {
+function queryTopSessions(db, n = 10, agent, since) {
+  const conditions = [];
+  const params = [];
   if (agent) {
-    return db.prepare(`SELECT * FROM sessions WHERE agent = ? ORDER BY total_cost_usd DESC LIMIT ?`).all(agent, n);
+    conditions.push("agent = ?");
+    params.push(agent);
   }
-  return db.prepare(`SELECT * FROM sessions ORDER BY total_cost_usd DESC LIMIT ?`).all(n);
+  if (since) {
+    conditions.push("started_at >= ?");
+    params.push(since);
+  }
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db.prepare(`SELECT * FROM sessions ${where} ORDER BY total_cost_usd DESC LIMIT ?`).all(...params, n);
 }
-function querySummary(db, period, machine, allMachines = false) {
+function querySummary(db, period, machine, allMachines = false, agent) {
   const rWhere = periodWhere(period);
   const sWhere = sessionPeriodWhere(period);
-  const machineClause = !allMachines && machine ? ` AND machine_id = '${machine.replace(/'/g, "''")}'` : "";
+  const machineClause = !allMachines && machine ? " AND machine_id = ?" : "";
+  const agentClause = agent ? " AND agent = ?" : "";
+  const params = [];
+  if (!allMachines && machine)
+    params.push(machine);
+  if (agent)
+    params.push(agent);
   const r = db.prepare(`
     SELECT COALESCE(SUM(cost_usd), 0) as total_usd,
            COUNT(*) as requests,
            COALESCE(SUM(input_tokens + output_tokens + cache_read_tokens + cache_create_tokens), 0) as tokens
-    FROM requests WHERE ${rWhere}${machineClause}
-  `).get();
+    FROM requests WHERE ${rWhere}${machineClause}${agentClause}
+  `).get(...params);
   const codexTotals = db.prepare(`
     SELECT COALESCE(SUM(total_cost_usd), 0) as cost_usd,
            COALESCE(SUM(total_tokens), 0) as tokens,
            COALESCE(SUM(request_count), 0) as requests,
            COUNT(*) as sessions
     FROM sessions
-    WHERE ${sWhere}${machineClause}
+    WHERE ${sWhere}${machineClause}${agentClause}
     AND id NOT IN (SELECT DISTINCT session_id FROM requests)
-  `).get();
+  `).get(...params);
   const requestSessionCount = db.prepare(`
     SELECT COUNT(DISTINCT session_id) as sessions
     FROM requests
-    WHERE ${rWhere}${machineClause}
-  `).get();
+    WHERE ${rWhere}${machineClause}${agentClause}
+  `).get(...params);
   return {
     total_usd: r.total_usd + codexTotals.cost_usd,
     requests: r.requests + codexTotals.requests,
@@ -1797,6 +1847,173 @@ var init_pg_migrations = __esm(() => {
   ];
 });
 
+// src/db/sync-pg.ts
+import { Worker, MessageChannel, receiveMessageOnPort } from "worker_threads";
+import { fileURLToPath } from "url";
+import { dirname, join as join9 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { translateSql, translateParams } from "@hasna/cloud";
+function translateSqliteDates(sql) {
+  let s = sql;
+  const isoDate = (expr) => `to_char(${expr}, 'YYYY-MM-DD')`;
+  s = s.replace(/DATE\('now',\s*'weekday 0',\s*'-7 days'\)/gi, isoDate("(date_trunc('week', now() + interval '1 day') - interval '1 day')"));
+  s = s.replace(/DATE\('now',\s*'start of month'\)/gi, isoDate("date_trunc('month', now())"));
+  s = s.replace(/DATE\('now',\s*'start of year'\)/gi, isoDate("date_trunc('year', now())"));
+  s = s.replace(/DATE\('now',\s*'(-?\d+)\s*days?'\)/gi, (_m, n) => isoDate(`now() + interval '${n} days'`));
+  s = s.replace(/DATE\('now',\s*(\$\d+)\s*\|\|\s*' days'\)/gi, (_m, p) => isoDate(`now() + ((${p}) || ' days')::interval`));
+  s = s.replace(/DATETIME\('now',\s*(\$\d+)\)/gi, (_m, p) => `(now() + (${p})::interval)`);
+  s = s.replace(/DATETIME\('now',\s*'([^']+)'\)/gi, (_m, lit) => `(now() + interval '${lit}')`);
+  const strftimeMap = { "%H": "HH24", "%Y": "YYYY", "%m": "MM", "%d": "DD", "%M": "MI", "%S": "SS" };
+  s = s.replace(/STRFTIME\('([^']+)',\s*([A-Za-z_][A-Za-z0-9_]*)\)/gi, (_m, fmt, col) => {
+    const pgFmt = Object.entries(strftimeMap).reduce((acc, [k, v]) => acc.split(k).join(v), fmt);
+    return `to_char(CAST("${col}" AS timestamptz), '${pgFmt}')`;
+  });
+  s = s.replace(/\bDATE\('now'\)/gi, isoDate("now()"));
+  s = s.replace(/\bDATETIME\('now'\)/gi, "now()");
+  s = s.replace(/\bDATETIME\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/gi, (_m, col) => `CAST("${col}" AS timestamptz)`);
+  s = s.replace(/\bDATE\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/gi, (_m, col) => `substr("${col}", 1, 10)`);
+  return s;
+}
+function resolveWorkerPath() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join9(here, "pg-sync-worker.ts"),
+    join9(here, "pg-sync-worker.js"),
+    join9(here, "..", "db", "pg-sync-worker.js")
+  ];
+  for (const candidate of candidates)
+    if (existsSync10(candidate))
+      return candidate;
+  return candidates[0];
+}
+
+class SyncPgAdapter {
+  worker;
+  port;
+  counter = 0;
+  constructor(dsn) {
+    const workerPath = resolveWorkerPath();
+    this.worker = new Worker(workerPath, { workerData: { dsn } });
+    this.worker.on("error", (err) => console.error(JSON.stringify({ evt: "pg_worker_error", message: err.message })));
+    const channel = new MessageChannel;
+    this.port = channel.port1;
+    this.worker.postMessage({ type: "init", port: channel.port2 }, [channel.port2]);
+  }
+  query(sql, params) {
+    const pgSql = translateSqliteDates(translateSql(sql, "pg"));
+    const pgParams = translateParams(params);
+    const id = ++this.counter;
+    const signal = new SharedArrayBuffer(4);
+    const sig = new Int32Array(signal);
+    Atomics.store(sig, 0, 0);
+    this.worker.postMessage({ id, sql: pgSql, params: pgParams, signal });
+    Atomics.wait(sig, 0, 0);
+    let received = receiveMessageOnPort(this.port);
+    for (let attempt = 0;!received && attempt < 1e6; attempt++)
+      received = receiveMessageOnPort(this.port);
+    if (!received)
+      throw new Error("SyncPgAdapter: no reply from worker");
+    const reply = received.message;
+    if (!reply.ok)
+      throw new Error(reply.error);
+    return { rows: reply.rows, rowCount: reply.rowCount };
+  }
+  run(sql, ...params) {
+    const result = this.query(sql, params);
+    return { changes: result.rowCount, lastInsertRowid: result.rows?.[0]?.["id"] ?? 0 };
+  }
+  get(sql, ...params) {
+    return this.query(sql, params).rows[0] ?? null;
+  }
+  all(sql, ...params) {
+    return this.query(sql, params).rows;
+  }
+  exec(sql) {
+    this.query(sql, []);
+  }
+  prepare(sql) {
+    const self = this;
+    return {
+      run: (...params) => self.run(sql, ...params),
+      get: (...params) => self.get(sql, ...params),
+      all: (...params) => self.all(sql, ...params),
+      finalize: () => {}
+    };
+  }
+  transaction(fn) {
+    return fn();
+  }
+  close() {
+    this.worker.terminate();
+  }
+}
+var init_sync_pg = () => {};
+
+// src/db/cloud.ts
+var exports_cloud = {};
+__export(exports_cloud, {
+  resolveSigningSecret: () => resolveSigningSecret,
+  openCloudDatabase: () => openCloudDatabase,
+  isCloudMode: () => isCloudMode,
+  getCloudDatabaseUrl: () => getCloudDatabaseUrl2,
+  createCloudPool: () => createCloudPool,
+  cloudMigrations: () => cloudMigrations,
+  authClientFromPool: () => authClientFromPool
+});
+import pg from "pg";
+function getCloudDatabaseUrl2() {
+  return process.env["HASNA_ECONOMY_DATABASE_URL"]?.trim() || process.env["ECONOMY_DATABASE_URL"]?.trim() || process.env["DATABASE_URL"]?.trim() || undefined;
+}
+function isCloudMode() {
+  const mode = process.env["HASNA_ECONOMY_STORAGE_MODE"]?.trim().toLowerCase();
+  if (mode === "cloud")
+    return true;
+  if (mode === "local")
+    return false;
+  return Boolean(getCloudDatabaseUrl2());
+}
+function resolveSigningSecret() {
+  return process.env["HASNA_ECONOMY_API_SIGNING_KEY"]?.trim() || process.env["HASNA_API_SIGNING_KEY"]?.trim() || process.env["API_KEY_SIGNING_SECRET"]?.trim() || undefined;
+}
+function openCloudDatabase(dsn = getCloudDatabaseUrl2()) {
+  if (!dsn) {
+    throw new Error("economy cloud mode requires a Postgres DSN: set HASNA_ECONOMY_DATABASE_URL (or ECONOMY_DATABASE_URL / DATABASE_URL)");
+  }
+  return new SyncPgAdapter(dsn);
+}
+function createCloudPool(dsn = getCloudDatabaseUrl2()) {
+  if (!dsn)
+    throw new Error("economy cloud mode requires a Postgres DSN (HASNA_ECONOMY_DATABASE_URL)");
+  const ssl = dsn.includes("sslmode=require") || dsn.includes("ssl=true") ? { rejectUnauthorized: false } : undefined;
+  const pool = new pg.Pool({ connectionString: dsn, ssl, max: Number(process.env["ECONOMY_PG_POOL_MAX"] ?? "5"), connectionTimeoutMillis: 1e4 });
+  pool.on("error", (err) => {
+    console.error(JSON.stringify({ evt: "pg_pool_error", message: err.message }));
+  });
+  return pool;
+}
+function authClientFromPool(pool) {
+  return {
+    async many(sql, params = []) {
+      const res = await pool.query(sql, params);
+      return res.rows;
+    },
+    async get(sql, params = []) {
+      const res = await pool.query(sql, params);
+      return res.rows[0] ?? null;
+    },
+    async execute(sql, params = []) {
+      await pool.query(sql, params);
+    }
+  };
+}
+function cloudMigrations() {
+  return PG_MIGRATIONS;
+}
+var init_cloud = __esm(() => {
+  init_sync_pg();
+  init_pg_migrations();
+});
+
 // src/ingest/billing.ts
 var exports_billing = {};
 __export(exports_billing, {
@@ -2093,15 +2310,15 @@ var init_open_projects = __esm(() => {
 });
 
 // src/lib/config.ts
-import { existsSync as existsSync10, readFileSync as readFileSync10, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
-import { dirname, join as join9 } from "path";
+import { existsSync as existsSync11, readFileSync as readFileSync10, writeFileSync, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2, join as join10 } from "path";
 function getConfigPath() {
-  return process.env["HASNA_ECONOMY_CONFIG_PATH"] ?? join9(getDataDir(), "config.json");
+  return process.env["HASNA_ECONOMY_CONFIG_PATH"] ?? join10(getDataDir(), "config.json");
 }
 function loadConfig() {
   try {
     const configPath = getConfigPath();
-    if (existsSync10(configPath)) {
+    if (existsSync11(configPath)) {
       const raw = readFileSync10(configPath, "utf-8");
       return { ...DEFAULTS, ...JSON.parse(raw) };
     }
@@ -4150,8 +4367,112 @@ function isAuthorizedRequest(req, path) {
 
 // src/server/serve.ts
 import { randomUUID } from "crypto";
-import { existsSync as existsSync11 } from "fs";
+import { existsSync as existsSync12 } from "fs";
 import { resolve, sep } from "path";
+init_cloud();
+import { verifyApiKey, ApiKeyStore } from "@hasna/contracts/auth";
+
+// src/openapi.ts
+var openApiSpec = {
+  openapi: "3.0.3",
+  info: {
+    title: "@hasna/economy self-hosted API",
+    version: "0.0.0",
+    description: "AI coding cost tracker \u2014 self-hosted control plane. Cloud mode is PURE REMOTE per Amendment A1: the serve process reads/writes the shared RDS Postgres directly with API-key auth via @hasna/contracts. All /v1 routes require a valid `economy:*` scoped API key (x-api-key or Authorization: Bearer). The foundation probes /health, /ready, /version are open."
+  },
+  servers: [{ url: "https://economy.hasna.xyz", description: "prod" }, { url: "http://localhost:3456", description: "local" }],
+  security: [{ apiKey: [] }, { bearer: [] }],
+  components: {
+    securitySchemes: {
+      apiKey: { type: "apiKey", in: "header", name: "x-api-key" },
+      bearer: { type: "http", scheme: "bearer" }
+    },
+    schemas: {
+      Envelope: { type: "object", properties: { data: {}, meta: { type: "object", additionalProperties: true } }, required: ["data"] },
+      Foundation: { type: "object", properties: { status: { type: "string" }, version: { type: "string" }, mode: { type: "string" }, service: { type: "string" } }, required: ["status", "version", "mode"] },
+      Error: { type: "object", properties: { error: { type: "string" }, message: { type: "string" } }, required: ["error"] },
+      MutationOk: { type: "object", properties: { ok: { type: "boolean" } } },
+      CostSummary: { type: "object", properties: { total_cost_usd: { type: "number" }, total_tokens: { type: "number" }, request_count: { type: "number" }, session_count: { type: "number" }, period: { type: "string" } }, additionalProperties: true },
+      Session: { type: "object", properties: { id: { type: "string" }, agent: { type: "string" }, project_path: { type: "string" }, project_name: { type: "string" }, started_at: { type: "string" }, ended_at: { type: "string", nullable: true }, total_cost_usd: { type: "number" }, total_tokens: { type: "number" }, request_count: { type: "number" } }, additionalProperties: true },
+      ModelBreakdown: { type: "object", additionalProperties: true },
+      ProjectBreakdown: { type: "object", additionalProperties: true },
+      AgentBreakdown: { type: "object", additionalProperties: true },
+      AccountBreakdown: { type: "object", additionalProperties: true },
+      DailyPoint: { type: "object", additionalProperties: true },
+      BudgetStatus: { type: "object", properties: { id: { type: "string" }, limit_usd: { type: "number" }, period: { type: "string" }, spent_usd: { type: "number" } }, additionalProperties: true },
+      CreateBudgetInput: { type: "object", properties: { limit_usd: { type: "number" }, alert_at_percent: { type: "number" }, period: { type: "string", enum: ["daily", "weekly", "monthly", "day", "week", "month"] }, project_path: { type: "string", nullable: true }, agent: { type: "string", nullable: true } }, required: ["limit_usd"] },
+      GoalStatus: { type: "object", additionalProperties: true },
+      CreateGoalInput: { type: "object", properties: { period: { type: "string", enum: ["day", "week", "month", "year"] }, limit_usd: { type: "number" }, project_path: { type: "string", nullable: true }, agent: { type: "string", nullable: true } }, required: ["limit_usd"] },
+      ModelPricing: { type: "object", additionalProperties: true },
+      CreatePricingInput: { type: "object", properties: { model: { type: "string" }, input_per_1m: { type: "number" }, output_per_1m: { type: "number" } }, required: ["model", "input_per_1m", "output_per_1m"] },
+      Subscription: { type: "object", additionalProperties: true },
+      CreateSubscriptionInput: { type: "object", properties: { provider: { type: "string" }, plan: { type: "string" }, monthly_fee_usd: { type: "number" }, included_usage_usd: { type: "number" }, agent: { type: "string", nullable: true } }, required: ["provider", "plan"] },
+      Project: { type: "object", additionalProperties: true },
+      CreateProjectInput: { type: "object", properties: { path: { type: "string" }, name: { type: "string" }, description: { type: "string" }, tags: { type: "array", items: { type: "string" } } }, required: ["path"] },
+      MachineInfo: { type: "object", additionalProperties: true },
+      BillingSummary: { type: "object", additionalProperties: true }
+    }
+  },
+  paths: {
+    "/health": { get: { operationId: "health", summary: "Liveness probe", security: [], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+    "/ready": { get: { operationId: "ready", summary: "Readiness probe (storage reachable + migrated)", security: [], responses: { "200": { description: "ready", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } }, "503": { description: "not ready", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+    "/version": { get: { operationId: "version", summary: "Version probe", security: [], responses: { "200": { description: "version", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+    "/v1/summary": { get: { operationId: "getSummary", summary: "Cost summary for a period", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/CostSummary" } } } } } } } } },
+    "/v1/sessions": { get: { operationId: "listSessions", summary: "List sessions", parameters: [{ name: "agent", in: "query", schema: { type: "string" } }, { name: "project", in: "query", schema: { type: "string" } }, { name: "search", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }, { name: "account", in: "query", schema: { type: "string" } }, { name: "limit", in: "query", schema: { type: "integer" } }, { name: "offset", in: "query", schema: { type: "integer" } }, { name: "since", in: "query", schema: { type: "string" } }, { name: "fields", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Session" } } } } } } } } } },
+    "/v1/sessions/{id}/requests": { get: { operationId: "getSessionRequests", summary: "Requests for a session", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } }, "404": { description: "not found", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } } } },
+    "/v1/top": { get: { operationId: "topSessions", summary: "Top sessions by cost", parameters: [{ name: "n", in: "query", schema: { type: "integer" } }, { name: "agent", in: "query", schema: { type: "string" } }, { name: "since", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Session" } } } } } } } } } },
+    "/v1/models": { get: { operationId: "modelBreakdown", summary: "Cost by model", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ModelBreakdown" } } } } } } } } } },
+    "/v1/projects": { get: { operationId: "projectBreakdown", summary: "Cost by project", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ProjectBreakdown" } } } } } } } } } },
+    "/v1/accounts": { get: { operationId: "accountBreakdown", summary: "Cost by account", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/AccountBreakdown" } } } } } } } } } },
+    "/v1/breakdown": { get: { operationId: "breakdown", summary: "Cost breakdown by dimension", parameters: [{ name: "by", in: "query", schema: { type: "string", enum: ["model", "project", "agent", "account"] } }, { name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/daily": { get: { operationId: "daily", summary: "Daily cost points", parameters: [{ name: "days", in: "query", schema: { type: "integer" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/DailyPoint" } } } } } } } } } },
+    "/v1/hourly": { get: { operationId: "hourly", summary: "Hourly cost points", parameters: [{ name: "hours", in: "query", schema: { type: "integer" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/machines": { get: { operationId: "listMachines", summary: "Known machines", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/MachineInfo" } } } } } } } } } },
+    "/v1/fleet": { get: { operationId: "fleet", summary: "Fleet summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/billing": { get: { operationId: "billing", summary: "Provider billing summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/BillingSummary" } } } } } } } } },
+    "/v1/billing/diff": { get: { operationId: "billingDiff", summary: "Billing vs tracked diff", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "threshold", in: "query", schema: { type: "number" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/usage": { get: { operationId: "usage", summary: "Usage snapshots + summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "agent", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/savings": { get: { operationId: "savings", summary: "Savings summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "agent", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+    "/v1/budgets": {
+      get: { operationId: "listBudgets", summary: "List budgets", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/BudgetStatus" } } } } } } } } },
+      post: { operationId: "createBudget", summary: "Create a budget", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateBudgetInput" } } } }, responses: { "200": { description: "created", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/BudgetStatus" } } } } } } } }
+    },
+    "/v1/budgets/{id}": { delete: { operationId: "deleteBudget", summary: "Delete a budget", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+    "/v1/goals": {
+      get: { operationId: "listGoals", summary: "List goals", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/GoalStatus" } } } } } } } } },
+      post: { operationId: "createGoal", summary: "Create a goal", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateGoalInput" } } } }, responses: { "200": { description: "created", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/GoalStatus" } } } } } } } }
+    },
+    "/v1/goals/{id}": { delete: { operationId: "deleteGoal", summary: "Delete a goal", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+    "/v1/pricing": {
+      get: { operationId: "listPricing", summary: "List model pricing", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ModelPricing" } } } } } } } } },
+      post: { operationId: "upsertPricing", summary: "Upsert model pricing", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreatePricingInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/ModelPricing" } } } } } } } }
+    },
+    "/v1/pricing/{model}": { delete: { operationId: "deletePricing", summary: "Delete model pricing", parameters: [{ name: "model", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+    "/v1/subscriptions": {
+      get: { operationId: "listSubscriptions", summary: "List subscriptions", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Subscription" } } } } } } } } },
+      post: { operationId: "upsertSubscription", summary: "Upsert a subscription", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateSubscriptionInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/Subscription" } } } } } } } }
+    },
+    "/v1/subscriptions/{id}": { delete: { operationId: "deleteSubscription", summary: "Delete a subscription", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+    "/v1/project-registry": {
+      get: { operationId: "listProjectRegistry", summary: "List registered projects", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Project" } } } } } } } } },
+      post: { operationId: "upsertProject", summary: "Register a project", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateProjectInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } }
+    },
+    "/v1/project-registry/{id}": { delete: { operationId: "deleteProject", summary: "Delete a registered project", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+    "/v1/sync": { post: { operationId: "sync", summary: "Trigger an ingest sync", requestBody: { required: false, content: { "application/json": { schema: { type: "object", properties: { sources: { type: "string" } } } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } }
+  }
+};
+
+// src/server/serve.ts
+function openApiDocument() {
+  const spec = openApiSpec;
+  return { ...spec, info: { ...spec["info"], version: packageMetadata.version } };
+}
+function serveMode() {
+  return isCloudMode() ? "self_hosted" : "local";
+}
+function foundationEnvelope(status, extra = {}) {
+  return { status, version: packageMetadata.version, mode: serveMode(), service: "economy", ...extra };
+}
 var CORS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,OPTIONS",
@@ -4217,19 +4538,20 @@ function dashboardPath(root, pathname) {
   const filePath = resolve(rootPath, relativePath);
   return filePath === rootPath || filePath.startsWith(rootPath + sep) ? filePath : null;
 }
+var FOUNDATION_PATHS = new Set(["/health", "/healthz", "/ready", "/readyz", "/version", "/openapi.json"]);
 function createServerFetch(apiHandler, dashboardDir = DEFAULT_DASHBOARD_DIR) {
   return async function fetch2(req) {
     const url = new URL(req.url);
-    if (url.pathname.startsWith("/api") || url.pathname === "/health") {
+    if (url.pathname.startsWith("/api") || url.pathname.startsWith("/v1") || FOUNDATION_PATHS.has(url.pathname)) {
       return apiHandler(req);
     }
-    if (existsSync11(dashboardDir)) {
+    if (existsSync12(dashboardDir)) {
       const filePath = dashboardPath(dashboardDir, url.pathname);
-      if (filePath && existsSync11(filePath)) {
+      if (filePath && existsSync12(filePath)) {
         return new Response(Bun.file(filePath));
       }
       const indexPath = dashboardPath(dashboardDir, "/");
-      if (indexPath && existsSync11(indexPath)) {
+      if (indexPath && existsSync12(indexPath)) {
         return new Response(Bun.file(indexPath));
       }
     }
@@ -4241,15 +4563,34 @@ function applyFields(obj, fields) {
     return obj;
   return Object.fromEntries(fields.map((f) => [f, obj[f] ?? null]));
 }
-function createHandler(db) {
+function createHandler(db, options = {}) {
   return async function handler(req) {
     const url = new URL(req.url);
-    const path = url.pathname;
+    const rawPath = url.pathname;
+    const path = rawPath.startsWith("/v1/") ? "/api" + rawPath.slice(3) : rawPath === "/v1" ? "/api" : rawPath;
     const method = req.method;
     if (method === "OPTIONS")
       return new Response(null, { status: 204, headers: CORS });
-    if (!isAuthorizedRequest(req, path))
+    if (method === "GET" && (rawPath === "/health" || rawPath === "/healthz")) {
+      return json(foundationEnvelope("ok"));
+    }
+    if (method === "GET" && (rawPath === "/version" || rawPath === "/v1/version")) {
+      return json(foundationEnvelope("ok"));
+    }
+    if (method === "GET" && (rawPath === "/ready" || rawPath === "/readyz")) {
+      const result = options.readyCheck ? await options.readyCheck() : { ready: true };
+      return json(foundationEnvelope(result.ready ? "ready" : "not_ready", result.detail ? { detail: result.detail } : {}), result.ready ? 200 : 503);
+    }
+    if (method === "GET" && rawPath === "/openapi.json") {
+      return json(openApiDocument());
+    }
+    if (options.authenticator) {
+      const decision = await options.authenticator.authenticate(req.headers, { method, path: rawPath });
+      if (!decision.ok)
+        return json({ error: decision.reason ?? "unauthorized", message: decision.message }, decision.status || 401);
+    } else if (!isAuthorizedRequest(req, path)) {
       return err("Unauthorized", 401);
+    }
     if (path === "/health")
       return ok({ status: "ok", ts: new Date().toISOString() });
     if (path === "/api/summary" && method === "GET") {
@@ -4314,7 +4655,8 @@ function createHandler(db) {
     if (path === "/api/top" && method === "GET") {
       const n = Number(url.searchParams.get("n") ?? 10);
       const agent = url.searchParams.get("agent") ?? undefined;
-      return ok(queryTopSessions(db, n, agent));
+      const since = url.searchParams.get("since") ?? undefined;
+      return ok(queryTopSessions(db, n, agent, since));
     }
     if (path === "/api/models" && method === "GET") {
       return ok(queryModelBreakdown(db));
@@ -4601,27 +4943,69 @@ function createHandler(db) {
     return err("Not found", 404);
   };
 }
+var APP = "economy";
+function isLocalHost(host) {
+  return ["127.0.0.1", "localhost", "::1"].includes(host);
+}
 function startServer(port = 3456, options = {}) {
-  const db = options.db ?? openDatabase();
-  ensurePricingSeeded(db);
-  const apiHandler = createHandler(db);
-  const hostname2 = options.hostname ?? getServeBindHost();
+  const cloud = options.db ? false : isCloudMode();
+  const hostname2 = options.hostname ?? (cloud ? process.env["ECONOMY_HOST"] ?? "0.0.0.0" : getServeBindHost());
+  const log = options.log ?? console.log;
+  const handlerOptions = {};
+  let db;
+  if (cloud) {
+    db = openCloudDatabase();
+    const pool = createCloudPool();
+    const signingSecret = resolveSigningSecret();
+    if (signingSecret) {
+      const keys = new ApiKeyStore(authClientFromPool(pool));
+      keys.ensureSchema().catch((e) => log(`api_keys ensureSchema: ${e instanceof Error ? e.message : String(e)}`));
+      handlerOptions.authenticator = verifyApiKey({
+        app: APP,
+        signingSecret,
+        isRevoked: keys.statusChecker(),
+        audit: (event) => log(JSON.stringify({ evt: "api_auth", outcome: event.outcome, kid: event.kid, reason: event.reason, path: event.path, status: event.status }))
+      });
+    } else if (!isLocalHost(hostname2)) {
+      throw new Error("economy-serve on a non-local host requires an API signing secret (HASNA_ECONOMY_API_SIGNING_KEY / API_KEY_SIGNING_SECRET)");
+    }
+    handlerOptions.readyCheck = async () => {
+      try {
+        const res = await pool.query("SELECT to_regclass($1) AS reg", ["public.requests"]);
+        if (!res.rows[0]?.reg)
+          return { ready: false, detail: "pending_migrations:requests" };
+        return { ready: true };
+      } catch (error) {
+        return { ready: false, detail: error instanceof Error ? error.message : "storage_unreachable" };
+      }
+    };
+  } else {
+    db = options.db ?? openDatabase();
+    ensurePricingSeeded(db);
+  }
+  const apiHandler = createHandler(db, handlerOptions);
   const server = Bun.serve({
     port,
     hostname: hostname2,
     fetch: createServerFetch(apiHandler, options.dashboardDir)
   });
   const address = `http://${hostname2 === "0.0.0.0" ? "localhost" : hostname2}:${server.port}`;
-  const log = options.log ?? console.log;
   log(`economy-serve listening on ${address}`);
   return server;
 }
 
 // src/server/index.ts
 function printHelp() {
-  console.log(`Usage: economy-serve [options]
+  console.log(`Usage: economy-serve [command] [options]
 
 REST API server for ${packageMetadata.name}
+Foundation probes: GET /health, /ready, /version -> { status, version, mode }
+Versioned API: /v1/* (API-key auth via @hasna/contracts in cloud mode)
+
+Commands:
+  (default)          start the HTTP server
+  migrate            apply the cloud Postgres schema + api_keys, then exit
+  version            print { status, version, mode }
 
 Options:
   -p, --port <port>  Port to bind (default: ECONOMY_PORT or 3456)
@@ -4647,18 +5031,46 @@ function parsePort(raw, label) {
   }
   return value;
 }
+async function runMigrate() {
+  const { getCloudDatabaseUrl: getCloudDatabaseUrl3, createCloudPool: createCloudPool2, authClientFromPool: authClientFromPool2, cloudMigrations: cloudMigrations2 } = await Promise.resolve().then(() => (init_cloud(), exports_cloud));
+  const { applyPgMigrations } = await import("@hasna/cloud");
+  const { ApiKeyStore: ApiKeyStore2 } = await import("@hasna/contracts/auth");
+  const dsn = getCloudDatabaseUrl3();
+  if (!dsn)
+    throw new Error("migrate requires a Postgres DSN: set HASNA_ECONOMY_DATABASE_URL (or ECONOMY_DATABASE_URL / DATABASE_URL)");
+  const result = await applyPgMigrations(dsn, cloudMigrations2(), "economy");
+  const pool = createCloudPool2(dsn);
+  try {
+    await new ApiKeyStore2(authClientFromPool2(pool)).ensureSchema();
+  } finally {
+    await pool.end().catch(() => {});
+  }
+  console.log(JSON.stringify({ evt: "migrate", service: result.service, applied: result.applied, alreadyApplied: result.alreadyApplied, errors: result.errors, api_keys: "ensured" }));
+  if (result.errors.length)
+    process.exit(1);
+}
 var args = process.argv.slice(2);
-if (args.includes("--help") || args.includes("-h")) {
-  printHelp();
+var sub = args[0];
+if (sub === "version") {
+  console.log(JSON.stringify({ status: "ok", version: packageMetadata.version, mode: process.env["HASNA_ECONOMY_STORAGE_MODE"] === "cloud" ? "self_hosted" : "local" }));
   process.exit(0);
 }
-if (args.includes("--version") || args.includes("-V")) {
+if (sub === "migrate") {
+  runMigrate().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+} else if (args.includes("--help") || args.includes("-h")) {
+  printHelp();
+  process.exit(0);
+} else if (args.includes("--version") || args.includes("-V")) {
   console.log(packageMetadata.version);
   process.exit(0);
-}
-try {
-  startServer(resolvePort(args));
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
+} else {
+  try {
+    startServer(resolvePort(args));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
 }