@hotmeshio/long-tail 0.1.0

package/build/services/auth/service-token.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateServiceToken = generateServiceToken;
+exports.validateServiceToken = validateServiceToken;
+exports.revokeServiceToken = revokeServiceToken;
+exports.listServiceTokens = listServiceTokens;
+const crypto = __importStar(require("crypto"));
+const bcryptjs_1 = __importDefault(require("bcryptjs"));
+const db_1 = require("../db");
+const TOKEN_PREFIX = 'lt_svc_';
+const INSERT_TOKEN = `
+  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)
+  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
+const GET_ALL_TOKENS = `
+  SELECT id, name, token_hash FROM lt_service_tokens
+  WHERE (expires_at IS NULL OR expires_at > NOW())`;
+const UPDATE_LAST_USED = `
+  UPDATE lt_service_tokens SET last_used_at = NOW() WHERE id = $1`;
+const DELETE_TOKEN = `
+  DELETE FROM lt_service_tokens WHERE id = $1`;
+const LIST_BY_SERVER = `
+  SELECT id, name, server_id, scopes, expires_at, last_used_at, created_at, updated_at
+  FROM lt_service_tokens WHERE server_id = $1 ORDER BY created_at`;
+/**
+ * Generate a new service token for an external MCP server.
+ * Returns the raw token once — it is never stored in plaintext.
+ */
+async function generateServiceToken(name, serverId, scopes, expiresAt) {
+    const rawToken = `${TOKEN_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
+    const tokenHash = await bcryptjs_1.default.hash(rawToken, 10);
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(INSERT_TOKEN, [
+        name, tokenHash, serverId, scopes, expiresAt || null,
+    ]);
+    return { id: rows[0].id, rawToken };
+}
+/**
+ * Validate a raw service token. Returns the record if valid, null otherwise.
+ */
+async function validateServiceToken(rawToken) {
+    if (!rawToken.startsWith(TOKEN_PREFIX))
+        return null;
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(GET_ALL_TOKENS);
+    for (const row of rows) {
+        if (await bcryptjs_1.default.compare(rawToken, row.token_hash)) {
+            await pool.query(UPDATE_LAST_USED, [row.id]);
+            const { token_hash, ...record } = row;
+            return record;
+        }
+    }
+    return null;
+}
+/**
+ * Revoke (delete) a service token by ID.
+ */
+async function revokeServiceToken(id) {
+    const pool = await (0, db_1.getPool)();
+    const result = await pool.query(DELETE_TOKEN, [id]);
+    return (result.rowCount ?? 0) > 0;
+}
+/**
+ * List service tokens for an MCP server (without hashes).
+ */
+async function listServiceTokens(serverId) {
+    const pool = await (0, db_1.getPool)();
+    const { rows } = await pool.query(LIST_BY_SERVER, [serverId]);
+    return rows;
+}

package/build/services/config/cache.d.ts

@@ -0,0 +1,2 @@
+import type { LTResolvedConfig } from '../../types';
+export declare function loadAllConfigs(): Promise<Map<string, LTResolvedConfig>>;

package/build/services/config/cache.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAllConfigs = loadAllConfigs;
+const read_1 = require("./read");
+async function loadAllConfigs() {
+    const configs = await (0, read_1.listWorkflowConfigs)();
+    const map = new Map();
+    for (const c of configs) {
+        map.set(c.workflow_type, {
+            invocable: c.invocable,
+            taskQueue: c.task_queue,
+            role: c.default_role,
+            roles: c.roles,
+            invocationRoles: c.invocation_roles,
+            consumes: c.consumes,
+            toolTags: c.tool_tags || [],
+            envelopeSchema: c.envelope_schema ?? null,
+            resolverSchema: c.resolver_schema ?? null,
+            cronSchedule: c.cron_schedule ?? null,
+            executeAs: c.execute_as ?? null,
+        });
+    }
+    return map;
+}

package/build/services/config/index.d.ts

@@ -0,0 +1,4 @@
+export { getWorkflowConfig, listWorkflowConfigs } from './read';
+export { upsertWorkflowConfig, deleteWorkflowConfig } from './write';
+export { loadAllConfigs } from './cache';
+export { getProviderData } from './provider';

package/build/services/config/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProviderData = exports.loadAllConfigs = exports.deleteWorkflowConfig = exports.upsertWorkflowConfig = exports.listWorkflowConfigs = exports.getWorkflowConfig = void 0;
+var read_1 = require("./read");
+Object.defineProperty(exports, "getWorkflowConfig", { enumerable: true, get: function () { return read_1.getWorkflowConfig; } });
+Object.defineProperty(exports, "listWorkflowConfigs", { enumerable: true, get: function () { return read_1.listWorkflowConfigs; } });
+var write_1 = require("./write");
+Object.defineProperty(exports, "upsertWorkflowConfig", { enumerable: true, get: function () { return write_1.upsertWorkflowConfig; } });
+Object.defineProperty(exports, "deleteWorkflowConfig", { enumerable: true, get: function () { return write_1.deleteWorkflowConfig; } });
+var cache_1 = require("./cache");
+Object.defineProperty(exports, "loadAllConfigs", { enumerable: true, get: function () { return cache_1.loadAllConfigs; } });
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "getProviderData", { enumerable: true, get: function () { return provider_1.getProviderData; } });

package/build/services/config/provider.d.ts

@@ -0,0 +1,2 @@
+import type { LTProviderData } from '../../types';
+export declare function getProviderData(consumes: string[], originId: string): Promise<LTProviderData>;

package/build/services/config/provider.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProviderData = getProviderData;
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+async function getProviderData(consumes, originId) {
+    if (!consumes.length || !originId)
+        return {};
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_PROVIDER_DATA, [originId, consumes]);
+    const result = {};
+    for (const row of rows) {
+        // Keep first (most recent) per workflow type
+        if (result[row.workflow_type])
+            continue;
+        let parsed = {};
+        try {
+            parsed = row.data ? JSON.parse(row.data) : {};
+        }
+        catch {
+            parsed = {};
+        }
+        result[row.workflow_type] = {
+            data: parsed,
+            completedAt: row.completed_at?.toISOString() || '',
+            workflowType: row.workflow_type,
+        };
+    }
+    return result;
+}

package/build/services/config/read.d.ts

@@ -0,0 +1,3 @@
+import type { LTWorkflowConfig } from '../../types';
+export declare function getWorkflowConfig(workflowType: string): Promise<LTWorkflowConfig | null>;
+export declare function listWorkflowConfigs(): Promise<LTWorkflowConfig[]>;

package/build/services/config/read.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorkflowConfig = getWorkflowConfig;
+exports.listWorkflowConfigs = listWorkflowConfigs;
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+async function getWorkflowConfig(workflowType) {
+    const pool = (0, db_1.getPool)();
+    const { rows: wfRows } = await pool.query(sql_1.GET_WORKFLOW, [workflowType]);
+    if (wfRows.length === 0)
+        return null;
+    const wf = wfRows[0];
+    const [rolesResult, invocationRolesResult] = await Promise.all([
+        pool.query(sql_1.GET_WORKFLOW_ROLES, [workflowType]),
+        pool.query(sql_1.GET_WORKFLOW_INVOCATION_ROLES, [workflowType]),
+    ]);
+    return {
+        workflow_type: wf.workflow_type,
+        invocable: wf.invocable,
+        task_queue: wf.task_queue,
+        default_role: wf.default_role,
+        description: wf.description,
+        roles: rolesResult.rows.map((r) => r.role),
+        invocation_roles: invocationRolesResult.rows.map((r) => r.role),
+        consumes: wf.consumes || [],
+        tool_tags: wf.tool_tags || [],
+        envelope_schema: wf.envelope_schema ?? null,
+        resolver_schema: wf.resolver_schema ?? null,
+        cron_schedule: wf.cron_schedule ?? null,
+        execute_as: wf.execute_as ?? null,
+    };
+}
+async function listWorkflowConfigs() {
+    const pool = (0, db_1.getPool)();
+    const [wfResult, rolesResult, invocationRolesResult] = await Promise.all([
+        pool.query(sql_1.LIST_ALL_WORKFLOWS),
+        pool.query(sql_1.LIST_ALL_ROLES),
+        pool.query(sql_1.LIST_ALL_INVOCATION_ROLES),
+    ]);
+    // Index sub-entities by workflow_type
+    const rolesMap = new Map();
+    for (const r of rolesResult.rows) {
+        if (!rolesMap.has(r.workflow_type))
+            rolesMap.set(r.workflow_type, []);
+        rolesMap.get(r.workflow_type).push(r.role);
+    }
+    const invocationRolesMap = new Map();
+    for (const r of invocationRolesResult.rows) {
+        if (!invocationRolesMap.has(r.workflow_type))
+            invocationRolesMap.set(r.workflow_type, []);
+        invocationRolesMap.get(r.workflow_type).push(r.role);
+    }
+    return wfResult.rows.map((wf) => ({
+        workflow_type: wf.workflow_type,
+        invocable: wf.invocable,
+        task_queue: wf.task_queue,
+        default_role: wf.default_role,
+        description: wf.description,
+        roles: rolesMap.get(wf.workflow_type) || [],
+        invocation_roles: invocationRolesMap.get(wf.workflow_type) || [],
+        consumes: wf.consumes || [],
+        tool_tags: wf.tool_tags || [],
+        envelope_schema: wf.envelope_schema ?? null,
+        resolver_schema: wf.resolver_schema ?? null,
+        cron_schedule: wf.cron_schedule ?? null,
+        execute_as: wf.execute_as ?? null,
+    }));
+}

package/build/services/config/sql.d.ts

@@ -0,0 +1,14 @@
+export declare const GET_WORKFLOW = "SELECT * FROM lt_config_workflows WHERE workflow_type = $1";
+export declare const GET_WORKFLOW_ROLES = "SELECT role FROM lt_config_roles WHERE workflow_type = $1 ORDER BY role";
+export declare const GET_WORKFLOW_INVOCATION_ROLES = "SELECT role FROM lt_config_invocation_roles WHERE workflow_type = $1 ORDER BY role";
+export declare const LIST_ALL_WORKFLOWS = "SELECT * FROM lt_config_workflows ORDER BY workflow_type";
+export declare const LIST_ALL_ROLES = "SELECT * FROM lt_config_roles ORDER BY workflow_type, role";
+export declare const LIST_ALL_INVOCATION_ROLES = "SELECT * FROM lt_config_invocation_roles ORDER BY workflow_type, role";
+export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
+export declare const UPSERT_WORKFLOW = "INSERT INTO lt_config_workflows\n  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as)\nVALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)\nON CONFLICT (workflow_type) DO UPDATE SET\n  invocable = EXCLUDED.invocable,\n  task_queue = EXCLUDED.task_queue,\n  default_role = EXCLUDED.default_role,\n  description = EXCLUDED.description,\n  consumes = EXCLUDED.consumes,\n  envelope_schema = EXCLUDED.envelope_schema,\n  resolver_schema = EXCLUDED.resolver_schema,\n  cron_schedule = EXCLUDED.cron_schedule,\n  tool_tags = EXCLUDED.tool_tags,\n  execute_as = EXCLUDED.execute_as";
+export declare const DELETE_CONFIG_ROLES = "DELETE FROM lt_config_roles WHERE workflow_type = $1";
+export declare const INSERT_CONFIG_ROLE = "INSERT INTO lt_config_roles (workflow_type, role) VALUES ($1, $2)";
+export declare const DELETE_INVOCATION_ROLES = "DELETE FROM lt_config_invocation_roles WHERE workflow_type = $1";
+export declare const INSERT_INVOCATION_ROLE = "INSERT INTO lt_config_invocation_roles (workflow_type, role) VALUES ($1, $2)";
+export declare const DELETE_WORKFLOW = "DELETE FROM lt_config_workflows WHERE workflow_type = $1";
+export declare const GET_PROVIDER_DATA = "SELECT workflow_type, data, completed_at\n  FROM lt_tasks\n WHERE origin_id = $1\n   AND workflow_type = ANY($2)\n   AND status = 'completed'\n ORDER BY completed_at DESC";

package/build/services/config/sql.js

@@ -0,0 +1,58 @@
+"use strict";
+// ------------------------------------------------------------------ //
+// Read queries                                                       //
+// ------------------------------------------------------------------ //
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GET_PROVIDER_DATA = exports.DELETE_WORKFLOW = exports.INSERT_INVOCATION_ROLE = exports.DELETE_INVOCATION_ROLES = exports.INSERT_CONFIG_ROLE = exports.DELETE_CONFIG_ROLES = exports.UPSERT_WORKFLOW = exports.ENSURE_ROLE_EXISTS = exports.LIST_ALL_INVOCATION_ROLES = exports.LIST_ALL_ROLES = exports.LIST_ALL_WORKFLOWS = exports.GET_WORKFLOW_INVOCATION_ROLES = exports.GET_WORKFLOW_ROLES = exports.GET_WORKFLOW = void 0;
+exports.GET_WORKFLOW = `\
+SELECT * FROM lt_config_workflows WHERE workflow_type = $1`;
+exports.GET_WORKFLOW_ROLES = `\
+SELECT role FROM lt_config_roles WHERE workflow_type = $1 ORDER BY role`;
+exports.GET_WORKFLOW_INVOCATION_ROLES = `\
+SELECT role FROM lt_config_invocation_roles WHERE workflow_type = $1 ORDER BY role`;
+exports.LIST_ALL_WORKFLOWS = `\
+SELECT * FROM lt_config_workflows ORDER BY workflow_type`;
+exports.LIST_ALL_ROLES = `\
+SELECT * FROM lt_config_roles ORDER BY workflow_type, role`;
+exports.LIST_ALL_INVOCATION_ROLES = `\
+SELECT * FROM lt_config_invocation_roles ORDER BY workflow_type, role`;
+// ------------------------------------------------------------------ //
+// Write / upsert queries                                             //
+// ------------------------------------------------------------------ //
+exports.ENSURE_ROLE_EXISTS = `\
+INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING`;
+exports.UPSERT_WORKFLOW = `\
+INSERT INTO lt_config_workflows
+  (workflow_type, invocable, task_queue, default_role, description, consumes, envelope_schema, resolver_schema, cron_schedule, tool_tags, execute_as)
+VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+ON CONFLICT (workflow_type) DO UPDATE SET
+  invocable = EXCLUDED.invocable,
+  task_queue = EXCLUDED.task_queue,
+  default_role = EXCLUDED.default_role,
+  description = EXCLUDED.description,
+  consumes = EXCLUDED.consumes,
+  envelope_schema = EXCLUDED.envelope_schema,
+  resolver_schema = EXCLUDED.resolver_schema,
+  cron_schedule = EXCLUDED.cron_schedule,
+  tool_tags = EXCLUDED.tool_tags,
+  execute_as = EXCLUDED.execute_as`;
+exports.DELETE_CONFIG_ROLES = `\
+DELETE FROM lt_config_roles WHERE workflow_type = $1`;
+exports.INSERT_CONFIG_ROLE = `\
+INSERT INTO lt_config_roles (workflow_type, role) VALUES ($1, $2)`;
+exports.DELETE_INVOCATION_ROLES = `\
+DELETE FROM lt_config_invocation_roles WHERE workflow_type = $1`;
+exports.INSERT_INVOCATION_ROLE = `\
+INSERT INTO lt_config_invocation_roles (workflow_type, role) VALUES ($1, $2)`;
+exports.DELETE_WORKFLOW = `\
+DELETE FROM lt_config_workflows WHERE workflow_type = $1`;
+// ------------------------------------------------------------------ //
+// Provider queries                                                   //
+// ------------------------------------------------------------------ //
+exports.GET_PROVIDER_DATA = `\
+SELECT workflow_type, data, completed_at
+  FROM lt_tasks
+ WHERE origin_id = $1
+   AND workflow_type = ANY($2)
+   AND status = 'completed'
+ ORDER BY completed_at DESC`;

package/build/services/config/write.d.ts

@@ -0,0 +1,5 @@
+import type { LTWorkflowConfig } from '../../types';
+export declare function upsertWorkflowConfig(config: LTWorkflowConfig & {
+    lifecycle?: any;
+}): Promise<LTWorkflowConfig>;
+export declare function deleteWorkflowConfig(workflowType: string): Promise<boolean>;

package/build/services/config/write.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertWorkflowConfig = upsertWorkflowConfig;
+exports.deleteWorkflowConfig = deleteWorkflowConfig;
+const db_1 = require("../db");
+const read_1 = require("./read");
+const sql_1 = require("./sql");
+async function upsertWorkflowConfig(config) {
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        // Ensure all referenced roles exist in lt_roles (FK constraints)
+        const allRoles = new Set([
+            config.default_role,
+            ...config.roles,
+            ...config.invocation_roles,
+        ]);
+        for (const role of allRoles) {
+            await client.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+        }
+        // Upsert the workflow row
+        await client.query(sql_1.UPSERT_WORKFLOW, [
+            config.workflow_type,
+            config.invocable,
+            config.task_queue,
+            config.default_role,
+            config.description,
+            config.consumes,
+            config.envelope_schema ?? null,
+            config.resolver_schema ?? null,
+            config.cron_schedule ?? null,
+            config.tool_tags || [],
+            config.execute_as ?? null,
+        ]);
+        // Replace roles
+        await client.query(sql_1.DELETE_CONFIG_ROLES, [config.workflow_type]);
+        for (const role of config.roles) {
+            await client.query(sql_1.INSERT_CONFIG_ROLE, [config.workflow_type, role]);
+        }
+        // Replace invocation roles
+        await client.query(sql_1.DELETE_INVOCATION_ROLES, [config.workflow_type]);
+        for (const role of config.invocation_roles) {
+            await client.query(sql_1.INSERT_INVOCATION_ROLE, [config.workflow_type, role]);
+        }
+        await client.query('COMMIT');
+    }
+    catch (err) {
+        await client.query('ROLLBACK');
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+    return (await (0, read_1.getWorkflowConfig)(config.workflow_type));
+}
+async function deleteWorkflowConfig(workflowType) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(sql_1.DELETE_WORKFLOW, [workflowType]);
+    return (rowCount ?? 0) > 0;
+}

package/build/services/controlplane/index.d.ts

@@ -0,0 +1,47 @@
+import { HotMesh } from '@hotmeshio/hotmesh';
+import type { QuorumProfile, ThrottleOptions } from '@hotmeshio/hotmesh/build/types/quorum';
+import type { ControlPlaneApp, StreamStats } from './types';
+export type { QuorumProfile, ThrottleOptions };
+/**
+ * Get or create a read-only HotMesh engine for control plane operations.
+ * The engine taps into the Postgres quorum channel for the given appId,
+ * enabling rollCall and throttle without running any workflows.
+ */
+export declare function getEngine(appId: string): Promise<HotMesh>;
+/**
+ * List all HotMesh application IDs from the `hotmesh_applications` table.
+ * Excludes soft-deleted (expired) entries.
+ */
+export declare function listApps(): Promise<ControlPlaneApp[]>;
+/**
+ * Execute a roll call against the mesh for a given appId.
+ * Broadcasts a ping and collects pong responses from all engines and workers.
+ */
+export declare function rollCall(appId: string, delay?: number): Promise<QuorumProfile[]>;
+/**
+ * Broadcast a throttle command to the mesh.
+ *
+ * @param appId — target application
+ * @param options.throttle — ms delay per message (-1 = pause, 0 = resume)
+ * @param options.topic — target a specific worker topic
+ * @param options.guid — target a specific engine/worker by GUID
+ */
+export declare function applyThrottle(appId: string, options: ThrottleOptions): Promise<boolean>;
+/**
+ * Get stream processing statistics for a given appId schema.
+ *
+ * @param schema — the Postgres schema (appId, e.g. "durable")
+ * @param duration — time range key (15m, 30m, 1h, 1d, 7d)
+ * @param streamName — optional: filter to a specific stream (task queue topic)
+ */
+export declare function getStreamStats(schema: string, duration?: string, streamName?: string | null): Promise<StreamStats>;
+/**
+ * Start the quorum→NATS bridge for an appId.
+ * Subscribes to the HotMesh quorum channel and republishes
+ * messages to NATS on `lt.mesh.*` topics.
+ */
+export declare function subscribeMesh(appId: string): Promise<void>;
+/**
+ * Check if a quorum bridge is active for an appId.
+ */
+export declare function isBridgeActive(appId: string): boolean;

package/build/services/controlplane/index.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEngine = getEngine;
+exports.listApps = listApps;
+exports.rollCall = rollCall;
+exports.applyThrottle = applyThrottle;
+exports.getStreamStats = getStreamStats;
+exports.subscribeMesh = subscribeMesh;
+exports.isBridgeActive = isBridgeActive;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pg_1 = require("pg");
+const config_1 = require("../../modules/config");
+const db_1 = require("../db");
+const sql_1 = require("./sql");
+const quorum_bridge_1 = require("./quorum-bridge");
+// ─── Engine cache ───────────────────────────────────────────────────────────
+/** Cached read-only HotMesh engines keyed by appId */
+const engines = new Map();
+/**
+ * Get or create a read-only HotMesh engine for control plane operations.
+ * The engine taps into the Postgres quorum channel for the given appId,
+ * enabling rollCall and throttle without running any workflows.
+ */
+async function getEngine(appId) {
+    const cached = engines.get(appId);
+    if (cached)
+        return cached;
+    const engine = await hotmesh_1.HotMesh.init({
+        appId,
+        engine: {
+            connection: { class: pg_1.Client, options: config_1.postgres_options },
+        },
+    });
+    engines.set(appId, engine);
+    return engine;
+}
+// ─── Application discovery ──────────────────────────────────────────────────
+/**
+ * List all HotMesh application IDs from the `hotmesh_applications` table.
+ * Excludes soft-deleted (expired) entries.
+ */
+async function listApps() {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.LIST_APPS);
+    return rows.map((r) => ({
+        appId: r.key.replace('hmsh:a:', ''),
+    }));
+}
+// ─── Roll call ──────────────────────────────────────────────────────────────
+/**
+ * Execute a roll call against the mesh for a given appId.
+ * Broadcasts a ping and collects pong responses from all engines and workers.
+ */
+async function rollCall(appId, delay) {
+    const engine = await getEngine(appId);
+    return engine.rollCall(delay);
+}
+// ─── Throttle ───────────────────────────────────────────────────────────────
+/**
+ * Broadcast a throttle command to the mesh.
+ *
+ * @param appId — target application
+ * @param options.throttle — ms delay per message (-1 = pause, 0 = resume)
+ * @param options.topic — target a specific worker topic
+ * @param options.guid — target a specific engine/worker by GUID
+ */
+async function applyThrottle(appId, options) {
+    const engine = await getEngine(appId);
+    return engine.throttle(options);
+}
+// ─── Stream statistics ──────────────────────────────────────────────────────
+/** Valid interval values (whitelist to prevent injection) */
+const VALID_INTERVALS = {
+    '15m': '15 minutes',
+    '30m': '30 minutes',
+    '1h': '1 hour',
+    '1d': '1 day',
+    '7d': '7 days',
+};
+/**
+ * Get stream processing statistics for a given appId schema.
+ *
+ * @param schema — the Postgres schema (appId, e.g. "durable")
+ * @param duration — time range key (15m, 30m, 1h, 1d, 7d)
+ * @param streamName — optional: filter to a specific stream (task queue topic)
+ */
+async function getStreamStats(schema, duration = '1h', streamName) {
+    const interval = VALID_INTERVALS[duration];
+    if (!interval)
+        throw new Error(`Invalid duration: ${duration}`);
+    const pool = (0, db_1.getPool)();
+    const stream = streamName || null;
+    const [pendingRes, processedRes, byStreamRes] = await Promise.all([
+        pool.query((0, sql_1.COUNT_PENDING)(schema), [stream]),
+        pool.query((0, sql_1.COUNT_PROCESSED_SINCE)(schema), [interval, stream]),
+        pool.query((0, sql_1.VOLUME_BY_STREAM)(schema), [interval, stream]),
+    ]);
+    return {
+        pending: pendingRes.rows[0]?.count ?? 0,
+        processed: processedRes.rows[0]?.count ?? 0,
+        byStream: byStreamRes.rows,
+    };
+}
+// ─── Quorum bridge ──────────────────────────────────────────────────────────
+/** Track which appIds have active quorum bridges */
+const activeBridges = new Set();
+/**
+ * Start the quorum→NATS bridge for an appId.
+ * Subscribes to the HotMesh quorum channel and republishes
+ * messages to NATS on `lt.mesh.*` topics.
+ */
+async function subscribeMesh(appId) {
+    if (activeBridges.has(appId))
+        return;
+    const engine = await getEngine(appId);
+    await (0, quorum_bridge_1.startQuorumBridge)(engine, appId);
+    activeBridges.add(appId);
+}
+/**
+ * Check if a quorum bridge is active for an appId.
+ */
+function isBridgeActive(appId) {
+    return activeBridges.has(appId);
+}

package/build/services/controlplane/quorum-bridge.d.ts

@@ -0,0 +1,15 @@
+import type { QuorumMessageCallback } from '@hotmeshio/hotmesh/build/types/quorum';
+/**
+ * Create a quorum callback that republishes messages to NATS.
+ */
+export declare function createQuorumBridgeCallback(appId: string): QuorumMessageCallback;
+/**
+ * Get the active quorum bridge callback (for unsubscription).
+ */
+export declare function getActiveCallback(): QuorumMessageCallback | null;
+/**
+ * Start the quorum bridge for a given HotMesh engine.
+ */
+export declare function startQuorumBridge(engine: {
+    subQuorum: (cb: QuorumMessageCallback) => Promise<void>;
+}, appId: string): Promise<void>;

package/build/services/controlplane/quorum-bridge.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createQuorumBridgeCallback = createQuorumBridgeCallback;
+exports.getActiveCallback = getActiveCallback;
+exports.startQuorumBridge = startQuorumBridge;
+const events_1 = require("../events");
+const logger_1 = require("../logger");
+/**
+ * Bridge HotMesh quorum messages to the NATS event system.
+ *
+ * Subscribes to a HotMesh engine's quorum channel via `subQuorum()`
+ * and republishes each message as an `LTEvent` on `lt.mesh.{type}`.
+ *
+ * Topic mapping (quorum subscription receives these types):
+ *   quorum type "pong"     → lt.events.mesh.pong
+ *   quorum type "ping"     → lt.events.mesh.ping
+ *   quorum type "job"      → lt.events.mesh.job
+ *   quorum type "work"     → lt.events.mesh.work
+ *   quorum type "activate" → lt.events.mesh.activate
+ *   quorum type "cron"     → lt.events.mesh.cron
+ *   quorum type "user"     → lt.events.mesh.user
+ *
+ * Note: throttle commands don't echo through the quorum subscription.
+ * The throttle route publishes a synthetic event directly to NATS.
+ */
+let activeCallback = null;
+/**
+ * Create a quorum callback that republishes messages to NATS.
+ */
+function createQuorumBridgeCallback(appId) {
+    const callback = (_topic, message) => {
+        const type = message.type || 'unknown';
+        const event = {
+            type: `mesh.${type}`,
+            source: 'controlplane',
+            workflowId: message.guid || '',
+            workflowName: '',
+            taskQueue: appId,
+            data: message,
+            timestamp: new Date().toISOString(),
+        };
+        events_1.eventRegistry.publish(event).catch(() => {
+            // fire-and-forget — NATS publish failures are non-critical
+        });
+    };
+    activeCallback = callback;
+    return callback;
+}
+/**
+ * Get the active quorum bridge callback (for unsubscription).
+ */
+function getActiveCallback() {
+    return activeCallback;
+}
+/**
+ * Start the quorum bridge for a given HotMesh engine.
+ */
+async function startQuorumBridge(engine, appId) {
+    const callback = createQuorumBridgeCallback(appId);
+    await engine.subQuorum(callback);
+    logger_1.loggerRegistry.info(`[controlplane] quorum bridge active for ${appId} → lt.mesh.*`);
+}