@hasna/economy 0.2.42 → 0.2.43

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this repository are tracked here. This project follows semantic versioning for published npm packages when practical.
 
+## @hasna/economy 0.2.43 - 2026-07-06
+
+- Added the self_hosted service surface: `economy-serve` foundation probes (`GET /health`, `/ready`, `/version` -> `{ status, version, mode }`) and a versioned `/v1` API covering summaries, sessions, breakdowns, budgets, goals, pricing, subscriptions, billing, and sync.
+- Added API-key authentication for the internet-facing `/v1` surface via `@hasna/contracts/auth` (stateless HMAC verify + revocation check).
+- Added Amendment A1 PURE-REMOTE cloud storage: the serve reads/writes the shared RDS Postgres directly through a worker-backed synchronous PG adapter (no local cache, no sync engine in the service).
+- Added a typed SDK client generated from the serve OpenAPI (`ECONOMY_API_URL` + `ECONOMY_API_KEY`).
+- Added the deploy surface: ARM64/bun `Dockerfile`, `docker-compose.yml`, `hasna.contract.json`, a `migrations/` directory + runner (`economy-serve migrate`).
+
 ## @hasna/economy 0.2.41 - 2026-06-24
 
 - Added root open-source project files for release notes, security reporting, contributing guidance, and conduct expectations.

package/dist/cli/index.js

@@ -4673,16 +4673,275 @@ var init_watch = __esm(() => {
   init_notification();
 });
 
+// src/db/sync-pg.ts
+import { Worker, MessageChannel, receiveMessageOnPort } from "worker_threads";
+import { fileURLToPath } from "url";
+import { dirname as dirname3, join as join14 } from "path";
+import { existsSync as existsSync16 } 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, fmt4, col) => {
+    const pgFmt = Object.entries(strftimeMap).reduce((acc, [k, v]) => acc.split(k).join(v), fmt4);
+    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 = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join14(here, "pg-sync-worker.ts"),
+    join14(here, "pg-sync-worker.js"),
+    join14(here, "..", "db", "pg-sync-worker.js")
+  ];
+  for (const candidate of candidates)
+    if (existsSync16(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
+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);
+    }
+  };
+}
+var init_cloud = __esm(() => {
+  init_sync_pg();
+  init_pg_migrations();
+});
+
+// src/openapi.ts
+var openApiSpec;
+var init_openapi = __esm(() => {
+  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
 var exports_serve = {};
 __export(exports_serve, {
   startServer: () => startServer,
+  openApiDocument: () => openApiDocument,
   createServerFetch: () => createServerFetch,
   createHandler: () => createHandler
 });
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync16 } from "fs";
+import { existsSync as existsSync17 } from "fs";
 import { resolve as resolve2, sep } from "path";
+import { verifyApiKey, ApiKeyStore } from "@hasna/contracts/auth";
+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 };
+}
 function json(data, status = 200) {
   return new Response(JSON.stringify(data), {
     status,
@@ -4743,16 +5002,16 @@ function dashboardPath(root, pathname) {
 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 (existsSync16(dashboardDir)) {
+    if (existsSync17(dashboardDir)) {
       const filePath = dashboardPath(dashboardDir, url.pathname);
-      if (filePath && existsSync16(filePath)) {
+      if (filePath && existsSync17(filePath)) {
         return new Response(Bun.file(filePath));
       }
       const indexPath = dashboardPath(dashboardDir, "/");
-      if (indexPath && existsSync16(indexPath)) {
+      if (indexPath && existsSync17(indexPath)) {
         return new Response(Bun.file(indexPath));
       }
     }
@@ -4764,15 +5023,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") {
@@ -5125,22 +5403,56 @@ function createHandler(db) {
     return err("Not found", 404);
   };
 }
+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;
 }
-var CORS, AGENT_ERROR, SYNC_SOURCES, DEFAULT_DASHBOARD_DIR;
+var CORS, AGENT_ERROR, SYNC_SOURCES, DEFAULT_DASHBOARD_DIR, FOUNDATION_PATHS, APP = "economy";
 var init_serve = __esm(() => {
   init_database();
   init_pricing();
@@ -5148,6 +5460,9 @@ var init_serve = __esm(() => {
   init_sync_all();
   init_billing_diff();
   init_database();
+  init_package_metadata();
+  init_cloud();
+  init_openapi();
   CORS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,OPTIONS",
@@ -5156,6 +5471,7 @@ var init_serve = __esm(() => {
   AGENT_ERROR = `agent must be one of: ${AGENTS.join(", ")}`;
   SYNC_SOURCES = ["all", ...AGENTS];
   DEFAULT_DASHBOARD_DIR = new URL("../../dashboard/dist", import.meta.url).pathname;
+  FOUNDATION_PATHS = new Set(["/health", "/healthz", "/ready", "/readyz", "/version", "/openapi.json"]);
 });
 
 // src/cli/commands/menubar.ts
@@ -5168,14 +5484,14 @@ __export(exports_menubar, {
 });
 import chalk6 from "chalk";
 import { execFileSync as execFileSync3 } from "child_process";
-import { cpSync, existsSync as existsSync17, mkdirSync as mkdirSync5, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "fs";
+import { cpSync, existsSync as existsSync18, mkdirSync as mkdirSync5, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir, arch } from "os";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 function getArch() {
   return arch() === "arm64" ? "arm64" : "x86_64";
 }
 function isInstalled() {
-  return existsSync17(APP_PATH);
+  return existsSync18(APP_PATH);
 }
 function isRunning() {
   try {
@@ -5212,8 +5528,8 @@ async function menubarInstall(opts) {
     console.error(chalk6.red(`\u2717 Failed to fetch release info: ${e instanceof Error ? e.message : String(e)}`));
     process.exit(1);
   }
-  const zipPath = join14(tmpdir(), `economy-bar-${cpuArch}.zip`);
-  const extractDir = join14(tmpdir(), "economy-bar-extracted");
+  const zipPath = join15(tmpdir(), `economy-bar-${cpuArch}.zip`);
+  const extractDir = join15(tmpdir(), "economy-bar-extracted");
   console.log(chalk6.cyan(`\u2192 Downloading ${assetUrl}...`));
   try {
     const res = await fetch(assetUrl, { signal: AbortSignal.timeout(60000) });
@@ -5233,7 +5549,7 @@ async function menubarInstall(opts) {
     execFileSync3("unzip", ["-q", zipPath, "-d", extractDir], { stdio: "ignore" });
     if (isInstalled())
       rmSync2(APP_PATH, { recursive: true, force: true });
-    cpSync(join14(extractDir, "Economy Bar.app"), APP_PATH, { recursive: true });
+    cpSync(join15(extractDir, "Economy Bar.app"), APP_PATH, { recursive: true });
     try {
       execFileSync3("xattr", ["-rd", "com.apple.quarantine", APP_PATH], { stdio: "ignore" });
     } catch {}
@@ -8924,8 +9240,8 @@ program.command("dashboard").description("Open the web dashboard (auto-starts se
   if (!serverRunning) {
     console.log(chalk7.cyan(`\u2192 Starting economy server on port ${port}...`));
     const { spawn } = await import("child_process");
-    const { resolve: resolve3, dirname: dirname3 } = await import("path");
-    const serveScript = resolve3(dirname3(process.argv[1]), "..", "server", "index.js");
+    const { resolve: resolve3, dirname: dirname4 } = await import("path");
+    const serveScript = resolve3(dirname4(process.argv[1]), "..", "server", "index.js");
     const child = spawn(process.execPath, [serveScript], {
       detached: true,
       stdio: "ignore",

package/dist/db/cloud.d.ts

@@ -0,0 +1,28 @@
+import type { DbAdapter } from '@hasna/cloud';
+import type { AuthQueryClient } from '@hasna/contracts/auth';
+import pg from 'pg';
+import type { SqliteAdapter as Database } from '@hasna/cloud';
+/** Resolve the cloud Postgres DSN from the standard env aliases. */
+export declare function getCloudDatabaseUrl(): string | undefined;
+/** True when the serve should run in cloud (RDS-direct) mode. */
+export declare function isCloudMode(): boolean;
+/** HMAC signing secret for API-key verification (server-held, never in a token). */
+export declare function resolveSigningSecret(): string | undefined;
+/**
+ * Open a pooled Postgres connection to the shared RDS. Returns a value typed as
+ * the SQLite `Database` the query layer expects — safe because `PgAdapter`
+ * implements the identical `DbAdapter` surface those functions rely on.
+ */
+export declare function openCloudDatabase(dsn?: string | undefined): Database;
+/** A raw pg Pool for auxiliary async work (API-key store, migrations). */
+export declare function createCloudPool(dsn?: string | undefined): pg.Pool;
+/**
+ * Adapt a pg Pool to the `@hasna/contracts/auth` `AuthQueryClient` surface
+ * (many/get/execute). This backs the `ApiKeyStore` without pulling in the
+ * generic vendored kit — economy's storage is the `@hasna/cloud` PG pool.
+ */
+export declare function authClientFromPool(pool: pg.Pool): AuthQueryClient;
+/** Ordered PG migrations applied by the migration runner (index = version). */
+export declare function cloudMigrations(): string[];
+export type { DbAdapter };
+//# sourceMappingURL=cloud.d.ts.map

package/dist/db/cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.d.ts","sourceRoot":"","sources":["../../src/db/cloud.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAA;AAI7D,oEAAoE;AACpE,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAOxD;AAED,iEAAiE;AACjE,wBAAgB,WAAW,IAAI,OAAO,CAKrC;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAOzD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,qBAAwB,GAAG,QAAQ,CASvE;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,GAAG,qBAAwB,GAAG,EAAE,CAAC,IAAI,CAYpE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,eAAe,CAcjE;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED,YAAY,EAAE,SAAS,EAAE,CAAA"}

package/dist/db/pg-sync-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pg-sync-worker.d.ts.map

package/dist/db/pg-sync-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-sync-worker.d.ts","sourceRoot":"","sources":["../../src/db/pg-sync-worker.ts"],"names":[],"mappings":""}

package/dist/db/sync-pg.d.ts

@@ -0,0 +1,23 @@
+import { type DbAdapter, type PreparedStatement, type RunResult } from '@hasna/cloud';
+/**
+ * Translate the closed set of SQLite date/time idioms the economy query layer
+ * uses into Postgres equivalents. Runs AFTER `translateSql` (so `?` are already
+ * `$n`). Timestamp columns are stored as ISO-8601 TEXT in both dialects, so bare
+ * `DATE(col)` casts through `timestamptz`. Ordered most-specific first.
+ */
+export declare function translateSqliteDates(sql: string): string;
+export declare class SyncPgAdapter implements DbAdapter {
+    private readonly worker;
+    private readonly port;
+    private counter;
+    constructor(dsn: string);
+    private query;
+    run(sql: string, ...params: unknown[]): RunResult;
+    get(sql: string, ...params: unknown[]): unknown;
+    all(sql: string, ...params: unknown[]): unknown[];
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    transaction<T>(fn: () => T): T;
+    close(): void;
+}
+//# sourceMappingURL=sync-pg.d.ts.map

package/dist/db/sync-pg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-pg.d.ts","sourceRoot":"","sources":["../../src/db/sync-pg.ts"],"names":[],"mappings":"AAeA,OAAO,EAAiC,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAIpH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiCxD;AAaD,qBAAa,aAAc,YAAW,SAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,OAAO,CAAI;gBAEP,GAAG,EAAE,MAAM;IAYvB,OAAO,CAAC,KAAK;IAsBb,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,SAAS;IAIjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO;IAG/C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAGjD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAGvB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB;IASvC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAI9B,KAAK,IAAI,IAAI;CAGd"}

package/dist/openapi.d.ts

@@ -0,0 +1,3 @@
+export declare const openApiSpec: Record<string, unknown>;
+export default openApiSpec;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAuF/C,CAAA;AACD,eAAe,WAAW,CAAA"}

package/dist/server/index.js

@@ -1847,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, {
@@ -2143,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) };
     }
@@ -4200,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",
@@ -4267,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));
       }
     }
@@ -4291,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") {
@@ -4652,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)
@@ -4698,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);
+  }
 }

package/dist/server/pg-sync-worker.js

@@ -0,0 +1,31 @@
+// @bun
+// src/db/pg-sync-worker.ts
+import { parentPort, workerData } from "worker_threads";
+import pg from "pg";
+pg.types.setTypeParser(20, (v) => v === null ? null : Number(v));
+pg.types.setTypeParser(1700, (v) => v === null ? null : Number(v));
+var dsn = workerData?.dsn;
+var ssl = dsn && (dsn.includes("sslmode=require") || dsn.includes("ssl=true")) ? { rejectUnauthorized: false } : undefined;
+var 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_worker_pool_error", message: err.message }));
+});
+var replyPort = null;
+parentPort?.on("message", (msg) => {
+  if (msg.type === "init") {
+    replyPort = msg.port;
+    return;
+  }
+  const { id, sql, params, signal } = msg;
+  const sig = new Int32Array(signal);
+  pool.query(sql, params).then((res) => ({ id, ok: true, rows: res.rows, rowCount: res.rowCount ?? 0 })).catch((err) => ({ id, ok: false, error: err instanceof Error ? err.message : String(err) })).then((response) => {
+    replyPort?.postMessage(response);
+    Atomics.store(sig, 0, 1);
+    Atomics.notify(sig, 0);
+  });
+});

package/dist/server/serve.d.ts

@@ -1,4 +1,23 @@
 import type { SqliteAdapter as Database } from '@hasna/cloud';
+/** The serve OpenAPI document (source of the generated SDK), version-synced. */
+export declare function openApiDocument(): Record<string, unknown>;
+/**
+ * Framework-agnostic API-key verifier shape (matches `@hasna/contracts/auth`
+ * `ApiKeyVerifier`). Kept structural so serve.ts has no hard dependency on the
+ * auth package; the entry point injects the real verifier.
+ */
+export interface ApiAuthenticator {
+    authenticate(headers: Headers, context?: {
+        method?: string | null;
+        path?: string | null;
+        requiredScopes?: readonly string[];
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        reason?: string;
+        message?: string;
+    }>;
+}
 interface StartServerOptions {
     db?: Database;
     dashboardDir?: string;
@@ -6,7 +25,18 @@ interface StartServerOptions {
     log?: (message: string) => void;
 }
 export declare function createServerFetch(apiHandler: (req: Request) => Promise<Response>, dashboardDir?: string): (req: Request) => Promise<Response>;
-export declare function createHandler(db: Database): (req: Request) => Promise<Response>;
+export interface HandlerOptions {
+    /** API-key verifier (from `@hasna/contracts/auth`). When present, every
+     * request outside the open foundation probes must present a valid
+     * `economy:*` scoped key. This is the internet-facing auth path. */
+    authenticator?: ApiAuthenticator;
+    /** Readiness probe proving storage is reachable + migrated. */
+    readyCheck?: () => Promise<{
+        ready: boolean;
+        detail?: string;
+    }>;
+}
+export declare function createHandler(db: Database, options?: HandlerOptions): (req: Request) => Promise<Response>;
 export declare function startServer(port?: number, options?: StartServerOptions): ReturnType<typeof Bun.serve>;
 export {};
 //# sourceMappingURL=serve.d.ts.map

package/dist/server/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/server/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAA;AAuC7D,UAAU,kBAAkB;IAC1B,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAqED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,YAAY,SAAwB,IACzF,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAwB7D;AAQD,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,IACV,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAsX/D;AAED,wBAAgB,WAAW,CAAC,IAAI,SAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAcvG"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/server/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,IAAI,QAAQ,EAAE,MAAM,cAAc,CAAA;AAkC7D,gFAAgF;AAChF,wBAAgB,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CACV,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,GAC7F,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/E;AAqBD,UAAU,kBAAkB;IAC1B,EAAE,CAAC,EAAE,QAAQ,CAAA;IACb,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAuED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,EAAE,YAAY,SAAwB,IACzF,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAwB7D;AAQD,MAAM,WAAW,cAAc;IAC7B;;wEAEoE;IACpE,aAAa,CAAC,EAAE,gBAAgB,CAAA;IAChC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAChE;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,GAAE,cAAmB,IACxC,KAAK,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAmZ/D;AAQD,wBAAgB,WAAW,CAAC,IAAI,SAAO,EAAE,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAkDvG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/economy",
-  "version": "0.2.42",
+  "version": "0.2.43",
   "description": "AI coding cost tracker — CLI + MCP server + REST API + web dashboard for Claude Code, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
     "CODE_OF_CONDUCT.md"
   ],
   "scripts": {
-    "build": "cd dashboard && bun run build && cd .. && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/server/index.ts --outdir dist/server --target bun --packages external && bun build src/otel/index.ts --outdir dist/otel --target bun --packages external && bun build src/index.ts --outdir dist --target bun --packages external && tsc --emitDeclarationOnly --outDir dist",
+    "build": "cd dashboard && bun run build && cd .. && bun build src/cli/index.ts --outdir dist/cli --target bun --packages external && bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external && bun build src/server/index.ts --outdir dist/server --target bun --packages external && bun build src/db/pg-sync-worker.ts --outdir dist/server --target bun --packages external && bun build src/otel/index.ts --outdir dist/otel --target bun --packages external && bun build src/index.ts --outdir dist --target bun --packages external && tsc --emitDeclarationOnly --outDir dist",
     "build:cli": "bun build src/cli/index.ts --outdir dist/cli --target bun --packages external",
     "build:mcp": "bun build src/mcp/index.ts --outdir dist/mcp --target bun --packages external",
     "build:server": "bun build src/server/index.ts --outdir dist/server --target bun --packages external",
@@ -71,15 +71,18 @@
   "dependencies": {
     "@hasna/accounts": "0.1.6",
     "@hasna/cloud": "0.1.24",
+    "@hasna/contracts": "0.4.1",
+    "@hasna/events": "^0.1.7",
     "@hasna/projects": "0.1.51",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
-    "zod": "^3.24.2",
-    "@hasna/events": "^0.1.7"
+    "pg": "8.13.1",
+    "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/pg": "^8.20.0",
     "bun-types": "latest",
     "typescript": "^5.7.2"
   },