@essentialai/cogent-server 3.4.2 → 3.4.3

package/dist/contract/control-plane-contract.d.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+/**
+ * Relay-side mirror of the control-plane ↔ relay API contract.
+ *
+ * The control plane (cogent-business, a SEPARATELY deployed service) defines the
+ * authoritative contract in `api/src/contract/relay-contract.ts`. The two repos
+ * cannot share a package, so the wire shape is duplicated here BY NECESSITY and
+ * pinned on both sides — the CP keeps `relay-contract.test.ts`, the relay keeps
+ * `control-plane.test.ts`, so a breaking change to either is caught before deploy.
+ * Vault: typescript-master-vault/concepts/Typesafe_Protocols.md (versioned
+ * request-response protocol) + Software_Version.md (semver major as the
+ * back-compat boundary).
+ *
+ * Hash discipline: the CP sends ALREADY-DERIVED hashes — `orgScope` = SHA-256(Org_ID)
+ * and `orgIdHash` = bcrypt(Org_ID). The relay stores these verbatim (it never sees
+ * the plaintext Org_ID). Only the channel `secret` arrives in plaintext (over the
+ * privileged TLS link) and is bcrypt-hashed HERE before storage.
+ */
+/** Major the relay supports. Reject any request whose major differs. */
+export declare const CONTROL_PLANE_API_MAJOR = 1;
+/** True if a contract version string is compatible with this relay's major. */
+export declare function isCompatibleVersion(version: string): boolean;
+declare const createChannelPayload: z.ZodObject<{
+    orgScope: z.ZodString;
+    orgIdHash: z.ZodString;
+    name: z.ZodString;
+    secret: z.ZodString;
+}, z.core.$strip>;
+declare const deleteChannelPayload: z.ZodObject<{
+    relaySessionId: z.ZodString;
+}, z.core.$strip>;
+declare const rotateOrgPayload: z.ZodObject<{
+    oldOrgScope: z.ZodString;
+    newOrgScope: z.ZodString;
+    newOrgIdHash: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Set an org's enforced tier quota (Epic 5, Story 5.1, FR20). The control plane owns
+ * the tier→quota mapping; the relay just persists the limits it enforces (the
+ * `org_quotas` row, keyed by `orgScope`) + the `tier` label for observability. Upsert
+ * semantics — idempotent, and a later tier change re-sends with new limits (5.7).
+ */
+declare const setOrgQuotaPayload: z.ZodObject<{
+    orgScope: z.ZodString;
+    tier: z.ZodString;
+    maxChannels: z.ZodNumber;
+    maxAgents: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Wire envelope, discriminated on `op`. `version` is validated separately (by
+ * major) so an incompatible-version request yields a clear version error rather
+ * than an opaque "op invalid" — see the route.
+ */
+export declare const RelayRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodString;
+    op: z.ZodLiteral<"channel.create">;
+    payload: z.ZodObject<{
+        orgScope: z.ZodString;
+        orgIdHash: z.ZodString;
+        name: z.ZodString;
+        secret: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodString;
+    op: z.ZodLiteral<"channel.delete">;
+    payload: z.ZodObject<{
+        relaySessionId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodString;
+    op: z.ZodLiteral<"org.rotate">;
+    payload: z.ZodObject<{
+        oldOrgScope: z.ZodString;
+        newOrgScope: z.ZodString;
+        newOrgIdHash: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    version: z.ZodString;
+    op: z.ZodLiteral<"org.setQuota">;
+    payload: z.ZodObject<{
+        orgScope: z.ZodString;
+        tier: z.ZodString;
+        maxChannels: z.ZodNumber;
+        maxAgents: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>], "op">;
+export type RelayRequest = z.infer<typeof RelayRequestSchema>;
+export type CreateChannelPayload = z.infer<typeof createChannelPayload>;
+export type DeleteChannelPayload = z.infer<typeof deleteChannelPayload>;
+export type RotateOrgPayload = z.infer<typeof rotateOrgPayload>;
+export type SetOrgQuotaPayload = z.infer<typeof setOrgQuotaPayload>;
+export {};
+//# sourceMappingURL=control-plane-contract.d.ts.map

package/dist/contract/control-plane-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane-contract.d.ts","sourceRoot":"","sources":["../../src/contract/control-plane-contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AAEH,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED,QAAA,MAAM,oBAAoB;;;;;iBASxB,CAAC;AAEH,QAAA,MAAM,oBAAoB;;iBAGxB,CAAC;AAEH,QAAA,MAAM,gBAAgB;;;;iBAIpB,CAAC;AAEH;;;;;GAKG;AACH,QAAA,MAAM,kBAAkB;;;;;iBAStB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yBAK7B,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/contract/control-plane-contract.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/**
+ * Relay-side mirror of the control-plane ↔ relay API contract.
+ *
+ * The control plane (cogent-business, a SEPARATELY deployed service) defines the
+ * authoritative contract in `api/src/contract/relay-contract.ts`. The two repos
+ * cannot share a package, so the wire shape is duplicated here BY NECESSITY and
+ * pinned on both sides — the CP keeps `relay-contract.test.ts`, the relay keeps
+ * `control-plane.test.ts`, so a breaking change to either is caught before deploy.
+ * Vault: typescript-master-vault/concepts/Typesafe_Protocols.md (versioned
+ * request-response protocol) + Software_Version.md (semver major as the
+ * back-compat boundary).
+ *
+ * Hash discipline: the CP sends ALREADY-DERIVED hashes — `orgScope` = SHA-256(Org_ID)
+ * and `orgIdHash` = bcrypt(Org_ID). The relay stores these verbatim (it never sees
+ * the plaintext Org_ID). Only the channel `secret` arrives in plaintext (over the
+ * privileged TLS link) and is bcrypt-hashed HERE before storage.
+ */
+/** Major the relay supports. Reject any request whose major differs. */
+export const CONTROL_PLANE_API_MAJOR = 1;
+/** True if a contract version string is compatible with this relay's major. */
+export function isCompatibleVersion(version) {
+    const major = Number(version.split(".")[0]);
+    return Number.isInteger(major) && major === CONTROL_PLANE_API_MAJOR;
+}
+const createChannelPayload = z.object({
+    /** SHA-256(Org_ID) — per-org scope (label-scope + quotas). Opaque; stored as-is. */
+    orgScope: z.string().min(1),
+    /** bcrypt(Org_ID) — the channel's Org_ID auth hash. Opaque; stored as-is. */
+    orgIdHash: z.string().min(1),
+    /** Human channel label (per-org scoped at the relay). */
+    name: z.string().min(1),
+    /** Channel password in plaintext; the relay bcrypts it before storage. */
+    secret: z.string().min(1),
+});
+const deleteChannelPayload = z.object({
+    /** The relay session id (UUID) returned by channel.create. */
+    relaySessionId: z.string().min(1),
+});
+const rotateOrgPayload = z.object({
+    oldOrgScope: z.string().min(1),
+    newOrgScope: z.string().min(1),
+    newOrgIdHash: z.string().min(1),
+});
+/**
+ * Set an org's enforced tier quota (Epic 5, Story 5.1, FR20). The control plane owns
+ * the tier→quota mapping; the relay just persists the limits it enforces (the
+ * `org_quotas` row, keyed by `orgScope`) + the `tier` label for observability. Upsert
+ * semantics — idempotent, and a later tier change re-sends with new limits (5.7).
+ */
+const setOrgQuotaPayload = z.object({
+    /** SHA-256(Org_ID) — the per-org key (matches org_quotas.org_scope). */
+    orgScope: z.string().min(1),
+    /** Tier label (free/small/medium/large/xlarge) — stored for observability. */
+    tier: z.string().min(1),
+    /** Max channels the org may own (enforced atomically on channel.create). */
+    maxChannels: z.number().int().nonnegative(),
+    /** Max concurrent collaborating agents (enforced at join time). */
+    maxAgents: z.number().int().nonnegative(),
+});
+/**
+ * Wire envelope, discriminated on `op`. `version` is validated separately (by
+ * major) so an incompatible-version request yields a clear version error rather
+ * than an opaque "op invalid" — see the route.
+ */
+export const RelayRequestSchema = z.discriminatedUnion("op", [
+    z.object({ version: z.string().min(1), op: z.literal("channel.create"), payload: createChannelPayload }),
+    z.object({ version: z.string().min(1), op: z.literal("channel.delete"), payload: deleteChannelPayload }),
+    z.object({ version: z.string().min(1), op: z.literal("org.rotate"), payload: rotateOrgPayload }),
+    z.object({ version: z.string().min(1), op: z.literal("org.setQuota"), payload: setOrgQuotaPayload }),
+]);
+//# sourceMappingURL=control-plane-contract.js.map

package/dist/contract/control-plane-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane-contract.js","sourceRoot":"","sources":["../../src/contract/control-plane-contract.ts"],"names":[],"mappings":"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"}

package/dist/db/index.d.ts

@@ -0,0 +1,5 @@
+export type { DbPoolConfig } from "./pool.js";
+export { createPool, query, withClient, withTransaction, closePool } from "./pool.js";
+export type { Migration } from "./migrate.js";
+export { loadMigrations, appliedVersions, migrateUp, migrateDown, isUpToDate, listTables, } from "./migrate.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtF,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EACL,cAAc,EACd,eAAe,EACf,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,cAAc,CAAC"}

package/dist/db/index.js

@@ -0,0 +1,3 @@
+export { createPool, query, withClient, withTransaction, closePool } from "./pool.js";
+export { loadMigrations, appliedVersions, migrateUp, migrateDown, isUpToDate, listTables, } from "./migrate.js";
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtF,OAAO,EACL,cAAc,EACd,eAAe,EACf,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,cAAc,CAAC"}

package/dist/db/migrate-cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=migrate-cli.d.ts.map

package/dist/db/migrate-cli.d.ts.map

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

package/dist/db/migrate-cli.js

@@ -0,0 +1,54 @@
+import { loadServerConfig } from "../config.js";
+import { createPool, closePool } from "./pool.js";
+import { migrateUp, migrateDown, appliedVersions } from "./migrate.js";
+/**
+ * CLI: `tsx src/db/migrate-cli.ts up` | `down [n]` | `status`.
+ * Reads COGENT_SERVER_DATABASE_URL (+ DB_* tuning) from env / config.json.
+ */
+async function main() {
+    const cmd = process.argv[2] ?? "up";
+    const cfg = loadServerConfig();
+    if (!cfg.DATABASE_URL) {
+        console.error("COGENT_SERVER_DATABASE_URL is not set — nothing to migrate.");
+        process.exit(1);
+    }
+    const pool = createPool({
+        connectionString: cfg.DATABASE_URL,
+        max: cfg.DB_POOL_MAX,
+        connectionTimeoutMs: cfg.DB_CONNECTION_TIMEOUT_MS,
+        idleTimeoutMs: cfg.DB_IDLE_TIMEOUT_MS,
+        statementTimeoutMs: cfg.DB_STATEMENT_TIMEOUT_MS,
+    });
+    try {
+        if (cmd === "up") {
+            const ran = await migrateUp(pool);
+            console.error(ran.length ? `Applied: ${ran.join(", ")}` : "Already up to date.");
+        }
+        else if (cmd === "down") {
+            // Guard: Number("all"/"-1"/"") -> NaN, and slice(-NaN) rolls back EVERYTHING.
+            // A typo must not drop the whole schema — require an explicit positive int.
+            const n = Number(process.argv[3] ?? "1");
+            if (!Number.isInteger(n) || n < 1) {
+                console.error(`down <n>: n must be a positive integer (got "${process.argv[3]}")`);
+                process.exit(1);
+            }
+            const rolled = await migrateDown(pool, n);
+            console.error(rolled.length ? `Rolled back: ${rolled.join(", ")}` : "Nothing to roll back.");
+        }
+        else if (cmd === "status") {
+            console.error(`Applied: ${(await appliedVersions(pool)).join(", ") || "(none)"}`);
+        }
+        else {
+            console.error(`Unknown command "${cmd}". Use: up | down [n] | status`);
+            process.exit(1);
+        }
+    }
+    finally {
+        await closePool(pool);
+    }
+}
+main().catch((err) => {
+    console.error("Migration failed:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=migrate-cli.js.map

package/dist/db/migrate-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-cli.js","sourceRoot":"","sources":["../../src/db/migrate-cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEvE;;;GAGG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACpC,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CAAC,6DAA6D,CAAC,CAAC;QAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC;QACtB,gBAAgB,EAAE,GAAG,CAAC,YAAY;QAClC,GAAG,EAAE,GAAG,CAAC,WAAW;QACpB,mBAAmB,EAAE,GAAG,CAAC,wBAAwB;QACjD,aAAa,EAAE,GAAG,CAAC,kBAAkB;QACrC,kBAAkB,EAAE,GAAG,CAAC,uBAAuB;KAChD,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YACjB,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC;QACnF,CAAC;aAAM,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;YAC1B,8EAA8E;YAC9E,4EAA4E;YAC5E,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;YACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,OAAO,CAAC,KAAK,CAAC,gDAAgD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAC1C,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC;QAC/F,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC,CAAC;QACpF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,oBAAoB,GAAG,gCAAgC,CAAC,CAAC;YACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,SAAS,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/db/migrate.d.ts

@@ -0,0 +1,31 @@
+import type { Pool } from "pg";
+/** One migration = a numeric-prefixed pair of up/down SQL files. */
+export interface Migration {
+    version: string;
+    up: string;
+    down: string;
+}
+/**
+ * Load all migrations from the migrations dir, ordered by their numeric prefix.
+ * Expects `<version>.up.sql` and `<version>.down.sql` pairs.
+ */
+export declare function loadMigrations(dir?: string): Promise<Migration[]>;
+/** Versions already applied, in apply order. */
+export declare function appliedVersions(pool: Pool): Promise<string[]>;
+/**
+ * Apply all unapplied migrations in order. Each migration's SQL AND its ledger
+ * insert run in a SINGLE transaction, so a failed migration leaves no partial
+ * schema and no ledger row (atomic + reversible). Idempotent: already-applied
+ * versions are skipped, so re-running is a no-op. Returns the versions applied.
+ */
+export declare function migrateUp(pool: Pool, dir?: string): Promise<string[]>;
+/**
+ * Roll back the last `n` applied migrations (most recent first). Each down.sql
+ * + its ledger delete run in one transaction. Returns the versions rolled back.
+ */
+export declare function migrateDown(pool: Pool, n?: number, dir?: string): Promise<string[]>;
+/** True if every on-disk migration has been applied. */
+export declare function isUpToDate(pool: Pool, dir?: string): Promise<boolean>;
+/** Convenience for tests/health: list table names in the public schema. */
+export declare function listTables(pool: Pool): Promise<string[]>;
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAK/B,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,GAAG,GAAE,MAAuB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAiBvF;AAYD,gDAAgD;AAChD,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAMnE;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAe3E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,SAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBpF;AAED,wDAAwD;AACxD,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI3E;AAED,2EAA2E;AAC3E,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAO9D"}

package/dist/db/migrate.js

@@ -0,0 +1,98 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { withClient, withTransaction } from "./pool.js";
+const MIGRATIONS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "migrations");
+/**
+ * Load all migrations from the migrations dir, ordered by their numeric prefix.
+ * Expects `<version>.up.sql` and `<version>.down.sql` pairs.
+ */
+export async function loadMigrations(dir = MIGRATIONS_DIR) {
+    const files = await fs.readdir(dir);
+    const versions = [
+        ...new Set(files
+            .filter((f) => f.endsWith(".up.sql"))
+            .map((f) => f.replace(/\.up\.sql$/, ""))),
+    ].sort(); // numeric prefix => lexical sort is correct for zero-padded versions
+    const migrations = [];
+    for (const version of versions) {
+        const up = await fs.readFile(path.join(dir, `${version}.up.sql`), "utf-8");
+        const down = await fs.readFile(path.join(dir, `${version}.down.sql`), "utf-8");
+        migrations.push({ version, up, down });
+    }
+    return migrations;
+}
+/** Ensure the ledger table exists. */
+async function ensureLedger(pool) {
+    await pool.query(`CREATE TABLE IF NOT EXISTS schema_migrations (
+       version    text PRIMARY KEY,
+       applied_at timestamptz NOT NULL DEFAULT now()
+     )`);
+}
+/** Versions already applied, in apply order. */
+export async function appliedVersions(pool) {
+    await ensureLedger(pool);
+    const res = await pool.query("SELECT version FROM schema_migrations ORDER BY version ASC");
+    return res.rows.map((r) => r.version);
+}
+/**
+ * Apply all unapplied migrations in order. Each migration's SQL AND its ledger
+ * insert run in a SINGLE transaction, so a failed migration leaves no partial
+ * schema and no ledger row (atomic + reversible). Idempotent: already-applied
+ * versions are skipped, so re-running is a no-op. Returns the versions applied.
+ */
+export async function migrateUp(pool, dir) {
+    await ensureLedger(pool);
+    const applied = new Set(await appliedVersions(pool));
+    const migrations = await loadMigrations(dir);
+    const ran = [];
+    for (const m of migrations) {
+        if (applied.has(m.version))
+            continue;
+        await withTransaction(pool, async (client) => {
+            await client.query(m.up);
+            await client.query("INSERT INTO schema_migrations (version) VALUES ($1)", [m.version]);
+        });
+        ran.push(m.version);
+    }
+    return ran;
+}
+/**
+ * Roll back the last `n` applied migrations (most recent first). Each down.sql
+ * + its ledger delete run in one transaction. Returns the versions rolled back.
+ */
+export async function migrateDown(pool, n = 1, dir) {
+    // Guard: a non-finite/NaN n would make slice(-n) return the WHOLE list and
+    // roll back everything. Require a positive integer (use a large n to mean "all").
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`migrateDown: n must be a positive integer (got ${n})`);
+    }
+    const applied = await appliedVersions(pool);
+    const byVersion = new Map((await loadMigrations(dir)).map((m) => [m.version, m]));
+    const toRollback = applied.slice(-n).reverse();
+    const rolled = [];
+    for (const version of toRollback) {
+        const m = byVersion.get(version);
+        if (!m) {
+            throw new Error(`Cannot roll back ${version}: no down migration found on disk`);
+        }
+        await withTransaction(pool, async (client) => {
+            await client.query(m.down);
+            await client.query("DELETE FROM schema_migrations WHERE version = $1", [version]);
+        });
+        rolled.push(version);
+    }
+    return rolled;
+}
+/** True if every on-disk migration has been applied. */
+export async function isUpToDate(pool, dir) {
+    const applied = new Set(await appliedVersions(pool));
+    const all = await loadMigrations(dir);
+    return all.every((m) => applied.has(m.version));
+}
+/** Convenience for tests/health: list table names in the public schema. */
+export async function listTables(pool) {
+    const res = await withClient(pool, (c) => c.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename"));
+    return res.rows.map((r) => r.tablename);
+}
+//# sourceMappingURL=migrate.js.map

package/dist/db/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"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"}

package/dist/db/migrations/0001_init_sessions.down.sql

@@ -0,0 +1,4 @@
+-- 0001_init_sessions (down): reverse of up. Children before parents.
+DROP TABLE IF EXISTS tokens;
+DROP TABLE IF EXISTS global_stats;
+DROP TABLE IF EXISTS sessions;

package/dist/db/migrations/0001_init_sessions.up.sql

@@ -0,0 +1,46 @@
+-- 0001_init_sessions (up): durable session storage for the business relay
+-- instance (FR35), JSONB-hybrid model.
+--
+-- Only the queryable / unique / auth-critical fields are normalized into columns;
+-- the rest of the session document (peers, messages, peerEvents, offline queues,
+-- channel mappings) lives in `state jsonb` — a 1:1 mirror of the file store's
+-- per-session JSON document, so updateSession is a whole-document UPDATE.
+
+CREATE TABLE sessions (
+  session_id   uuid PRIMARY KEY,
+  label        text,
+  secret_hash  text NOT NULL,
+  -- Business Edition: bcrypt hash of the Org_ID (auth) + stable SHA-256 scope
+  -- (label namespacing). Both NULL on free/public channels.
+  org_id_hash  text,
+  org_scope    text,
+  creator_ip   text,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  -- Full mutable session document (everything except tokens + the columns above).
+  state        jsonb NOT NULL DEFAULT '{}'::jsonb
+);
+
+-- Per-org label scope (Story 2.3 analogue): a label is unique WITHIN its scope;
+-- free/public channels collapse to the empty scope (global uniqueness). Two orgs
+-- can both hold 'sprint-42' because their scopes differ.
+CREATE UNIQUE INDEX sessions_scope_label_uniq
+  ON sessions (COALESCE(org_scope, ''), label)
+  WHERE label IS NOT NULL;
+
+-- Tokens stay normalized + indexed: bearer-token auth looks a session up by its
+-- SHA-256 token hash on every request (getSessionByTokenHash).
+CREATE TABLE tokens (
+  token_hash  text PRIMARY KEY,
+  session_id  uuid NOT NULL REFERENCES sessions(session_id) ON DELETE CASCADE,
+  peer_id     text,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX tokens_session_idx ON tokens (session_id);
+
+-- Single-row monotonic global message counter (mirrors global-stats.json).
+CREATE TABLE global_stats (
+  id             boolean PRIMARY KEY DEFAULT true,
+  total_messages bigint NOT NULL DEFAULT 0,
+  CONSTRAINT global_stats_singleton CHECK (id)
+);
+INSERT INTO global_stats (id, total_messages) VALUES (true, 0);

package/dist/db/migrations/0002_org_quotas.down.sql

@@ -0,0 +1,2 @@
+-- 0002_org_quotas (down)
+DROP TABLE IF EXISTS org_quotas;

package/dist/db/migrations/0002_org_quotas.up.sql

@@ -0,0 +1,13 @@
+-- 0002_org_quotas (up): per-org tier quotas, enforced atomically by the relay
+-- (FR7/FR8). The control plane (E3) provisions/updates a row per org (keyed by
+-- the org's stable SHA-256 scope); the relay reads + row-locks it to enforce
+-- limits under concurrency. A missing row means "not yet provisioned" -> the
+-- relay does not cap (fail-open pre-E3; tests insert rows explicitly).
+
+CREATE TABLE org_quotas (
+  org_scope     text PRIMARY KEY,
+  tier          text NOT NULL DEFAULT 'free',
+  max_channels  integer NOT NULL,
+  max_agents    integer NOT NULL,
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);

package/dist/db/pool.d.ts

@@ -0,0 +1,39 @@
+import type { Pool, PoolClient, QueryResult, QueryResultRow } from "pg";
+/** Pool tuning, sourced from server config (COGENT_SERVER_DB_*). */
+export interface DbPoolConfig {
+    connectionString: string;
+    /** Max concurrent connections — the bounded ceiling (back-pressure). */
+    max: number;
+    /** Acquire timeout (ms): a connect that can't be served in this window
+     *  rejects rather than hanging — the graceful-degradation lever. */
+    connectionTimeoutMs: number;
+    /** Idle client reaped after this long (ms). */
+    idleTimeoutMs: number;
+    /** Per-statement server-side timeout (ms); 0 disables. */
+    statementTimeoutMs: number;
+}
+/**
+ * Create a bounded Postgres connection pool.
+ *
+ * The pool size is capped at `max`; when all connections are in use, further
+ * acquisitions WAIT, and if none frees within `connectionTimeoutMs` the acquire
+ * REJECTS with an error instead of hanging or growing unbounded (the DB-pool
+ * analogue of stream back-pressure — bounded buffer + timeout, never a crash).
+ *
+ * An `error` listener is attached because `pg` emits errors from IDLE clients
+ * on the pool object (not via any await); without a listener those would be
+ * unhandled and could crash the process.
+ */
+export declare function createPool(cfg: DbPoolConfig): Pool;
+/** Run a single query on a pooled connection (auto-acquired + released). */
+export declare function query<R extends QueryResultRow = QueryResultRow>(pool: Pool, text: string, params?: unknown[]): Promise<QueryResult<R>>;
+/** Acquire a client, run `fn`, and ALWAYS release it (even on throw). */
+export declare function withClient<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
+/**
+ * Run `fn` inside a transaction: BEGIN → fn → COMMIT, or ROLLBACK on any throw.
+ * The client is always released.
+ */
+export declare function withTransaction<T>(pool: Pool, fn: (client: PoolClient) => Promise<T>): Promise<T>;
+/** Gracefully drain and close the pool (call on shutdown). */
+export declare function closePool(pool: Pool): Promise<void>;
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/db/pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,IAAI,CAAC;AAIxE,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ;wEACoE;IACpE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAgBlD;AAED,4EAA4E;AAC5E,wBAAsB,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnE,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAEzB;AAED,yEAAyE;AACzE,wBAAsB,UAAU,CAAC,CAAC,EAChC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,8DAA8D;AAC9D,wBAAsB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzD"}

package/dist/db/pool.js

@@ -0,0 +1,72 @@
+import pg from "pg";
+const { Pool: PgPool } = pg;
+/**
+ * Create a bounded Postgres connection pool.
+ *
+ * The pool size is capped at `max`; when all connections are in use, further
+ * acquisitions WAIT, and if none frees within `connectionTimeoutMs` the acquire
+ * REJECTS with an error instead of hanging or growing unbounded (the DB-pool
+ * analogue of stream back-pressure — bounded buffer + timeout, never a crash).
+ *
+ * An `error` listener is attached because `pg` emits errors from IDLE clients
+ * on the pool object (not via any await); without a listener those would be
+ * unhandled and could crash the process.
+ */
+export function createPool(cfg) {
+    const pool = new PgPool({
+        connectionString: cfg.connectionString,
+        max: cfg.max,
+        connectionTimeoutMillis: cfg.connectionTimeoutMs,
+        idleTimeoutMillis: cfg.idleTimeoutMs,
+        // Server-side per-statement timeout bounds runaway queries.
+        statement_timeout: cfg.statementTimeoutMs > 0 ? cfg.statementTimeoutMs : undefined,
+    });
+    // An idle client error (e.g. the DB dropped the connection) must not crash us.
+    pool.on("error", (err) => {
+        console.error("[db] idle client error:", err.message);
+    });
+    return pool;
+}
+/** Run a single query on a pooled connection (auto-acquired + released). */
+export async function query(pool, text, params) {
+    return pool.query(text, params);
+}
+/** Acquire a client, run `fn`, and ALWAYS release it (even on throw). */
+export async function withClient(pool, fn) {
+    const client = await pool.connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Run `fn` inside a transaction: BEGIN → fn → COMMIT, or ROLLBACK on any throw.
+ * The client is always released.
+ */
+export async function withTransaction(pool, fn) {
+    return withClient(pool, async (client) => {
+        try {
+            await client.query("BEGIN");
+            const result = await fn(client);
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (err) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch {
+                // A rollback failure (e.g. the connection died) is secondary to the
+                // original error — swallow it so the real cause propagates.
+            }
+            throw err;
+        }
+    });
+}
+/** Gracefully drain and close the pool (call on shutdown). */
+export async function closePool(pool) {
+    await pool.end();
+}
+//# sourceMappingURL=pool.js.map

package/dist/db/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../../src/db/pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,CAAC;AAGpB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAgB5B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,GAAiB;IAC1C,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC;QACtB,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QACtC,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,uBAAuB,EAAE,GAAG,CAAC,mBAAmB;QAChD,iBAAiB,EAAE,GAAG,CAAC,aAAa;QACpC,4DAA4D;QAC5D,iBAAiB,EAAE,GAAG,CAAC,kBAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS;KACnF,CAAC,CAAC;IAEH,+EAA+E;IAC/E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;QACvB,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AACd,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,IAAU,EACV,IAAY,EACZ,MAAkB;IAElB,OAAO,IAAI,CAAC,KAAK,CAAI,IAAI,EAAE,MAA6B,CAAC,CAAC;AAC5D,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,IAAU,EACV,EAAsC;IAEtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,EAAsC;IAEtC,OAAO,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;QACvC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;YAChC,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,oEAAoE;gBACpE,4DAA4D;YAC9D,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAU;IACxC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;AACnB,CAAC"}