@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/hotmesh/index.js

@@ -1,15 +1,43 @@
 "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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HotMesh = void 0;
-const key_1 = require("../../modules/key");
 const utils_1 = require("../../modules/utils");
 const factory_1 = require("../connector/factory");
-const engine_1 = require("../engine");
 const logger_1 = require("../logger");
-const quorum_1 = require("../quorum");
 const router_1 = require("../router");
-const worker_1 = require("../worker");
-const enums_1 = require("../../modules/enums");
+// Submodules
+const Validation = __importStar(require("./validation"));
+const Init = __importStar(require("./init"));
+const PubSub = __importStar(require("./pubsub"));
+const Quorum = __importStar(require("./quorum"));
+const Deployment = __importStar(require("./deployment"));
+const Jobs = __importStar(require("./jobs"));
+// Codec and credential re-exports
+const serializer_1 = require("../serializer");
+const WorkerCredentials = __importStar(require("../worker/credentials"));
 /**
  * A distributed service mesh that turns Postgres into a durable workflow
  * orchestration engine. Every `HotMesh.init()` call creates a **point of
@@ -89,67 +117,6 @@ const enums_1 = require("../../modules/enums");
  * const result = await hotMesh.pubsub('order.placed', { id: 'ORD-456' });
  * ```
  *
- * ## Quorum: The Mesh Control Plane
- *
- * The quorum channel is a broadcast bus available to every mesh member.
- * Use it for operational control, observability, and custom messaging.
- *
- * ```typescript
- * // Roll call — discover every engine and worker in the mesh
- * const members = await hotMesh.rollCall();
- * // => [{ engine_id, worker_topic, throttle, system: { CPULoad, ... } }, ...]
- *
- * // Subscribe to ALL quorum traffic (throttle, activate, pong, job, user)
- * await hotMesh.subQuorum((topic, message) => {
- *   switch (message.type) {
- *     case 'pong':      // roll call response from a mesh member
- *       console.log(`Member ${message.guid} on topic ${message.profile?.worker_topic}`);
- *       break;
- *     case 'throttle':  // a throttle command was broadcast
- *       console.log(`Throttle ${message.throttle}ms on ${message.topic ?? 'all'}`);
- *       break;
- *     case 'activate':  // a version activation is in progress
- *       console.log(`Activating version ${message.until_version}`);
- *       break;
- *     case 'job':       // a workflow completed and published its result
- *       console.log(`Job done on ${message.topic}:`, message.job);
- *       break;
- *     case 'user':      // a custom user message
- *       console.log(`User event ${message.topic}:`, message.message);
- *       break;
- *   }
- * });
- *
- * // Publish a custom message to every mesh member
- * await hotMesh.pubQuorum({
- *   type: 'user',
- *   topic: 'deploy.notify',
- *   message: { version: '2.1.0', deployer: 'ci-pipeline' },
- * });
- * ```
- *
- * ## Throttling: Backpressure Across the Mesh
- *
- * Throttle commands propagate instantly to every targeted member via
- * the quorum channel, providing fine-grained flow control.
- *
- * ```typescript
- * // Pause the ENTIRE mesh (emergency stop)
- * await hotMesh.throttle({ throttle: -1 });
- *
- * // Resume the entire mesh
- * await hotMesh.throttle({ throttle: 0 });
- *
- * // Slow a specific worker topic to 1 message per 500ms
- * await hotMesh.throttle({ throttle: 500, topic: 'order.process' });
- *
- * // Throttle a single engine/worker instance by GUID
- * await hotMesh.throttle({ throttle: 2000, guid: 'abc-123' });
- *
- * // Combine: throttle a specific topic on a specific instance
- * await hotMesh.throttle({ throttle: 1000, guid: 'abc-123', topic: 'order.process' });
- * ```
- *
  * ## Lifecycle
  *
  * 1. **`init`** — Create an engine + workers; join the quorum.
@@ -161,127 +128,50 @@ const enums_1 = require("../../modules/enums");
  * ## Higher-Level Modules
  *
  * For most use cases, prefer the higher-level wrappers:
- * - **Durable** — Temporal-style durable workflow functions.
+ * - **Durable** — Durable workflow functions with replay and retry.
  * - **Virtual** — Virtual network functions and idempotent RPC.
  *
  * @see {@link https://hotmeshio.github.io/sdk-typescript/} - API reference
  */
 class HotMesh {
+    /**
+     * @private
+     */
+    constructor() {
+        /**
+         * @private
+         */
+        this.engine = null;
+        /**
+         * @private
+         */
+        this.quorum = null;
+        /**
+         * @private
+         */
+        this.workers = [];
+    }
     /**
      * @private
      */
     verifyAndSetNamespace(namespace) {
-        if (!namespace) {
-            this.namespace = key_1.HMNS;
-        }
-        else if (!namespace.match(/^[A-Za-z0-9-]+$/)) {
-            throw new Error(`config.namespace [${namespace}] is invalid`);
-        }
-        else {
-            this.namespace = namespace;
-        }
+        Validation.verifyAndSetNamespace(this, namespace);
     }
     /**
      * @private
      */
     verifyAndSetAppId(appId) {
-        if (!appId?.match(/^[A-Za-z0-9-]+$/)) {
-            throw new Error(`config.appId [${appId}] is invalid`);
-        }
-        else if (appId === 'a') {
-            throw new Error(`config.appId [${appId}] is reserved`);
-        }
-        else {
-            this.appId = appId;
-        }
+        Validation.verifyAndSetAppId(this, appId);
     }
     /**
-     * Instance initializer. Workers are configured
-     * similarly to the engine, but as an array with
-     * multiple worker objects.
-     *
-     * ## Retry Policy Configuration
+     * Create a HotMesh instance with an engine and optional workers.
      *
-     * HotMesh supports retry policies with exponential backoff. Retry behavior
-     * can be configured independently on both the `engine` and individual
-     * `workers`. They are **not inherited**; each operates at its own level.
+     * The engine manages workflow state in Postgres. Workers are callback
+     * functions that consume messages from Postgres streams — they can
+     * run on the same process or on entirely separate servers.
      *
-     * - **Engine `retryPolicy`**: Stamps messages the engine publishes with
-     *   retry metadata (stored as Postgres columns). Workers that consume
-     *   these messages will use the embedded config when handling failures.
-     * - **Worker `retryPolicy`**: Used as the fallback when the consumed
-     *   message does not carry explicit retry metadata.
-     *
-     * @example Basic Configuration
-     * ```typescript
-     * const hotMesh = await HotMesh.init({
-     *   appId: 'myapp',
-     *   engine: {
-     *     connection: {
-     *       class: Postgres,
-     *       options: {
-     *         connectionString: 'postgresql://usr:pwd@localhost:5432/db',
-     *       }
-     *     }
-     *   },
-     *   workers: [...]
-     * });
-     * ```
-     *
-     * @example Engine Retry Policy
-     * ```typescript
-     * const hotMesh = await HotMesh.init({
-     *   appId: 'myapp',
-     *   engine: {
-     *     connection: {
-     *       class: Postgres,
-     *       options: { connectionString: 'postgresql://...' }
-     *     },
-     *     retryPolicy: {
-     *       maximumAttempts: 5,
-     *       backoffCoefficient: 2,
-     *       maximumInterval: '300s'
-     *     }
-     *   }
-     * });
-     * ```
-     *
-     * @example Worker Retry Policy
-     * ```typescript
-     * const hotMesh = await HotMesh.init({
-     *   appId: 'myapp',
-     *   engine: { connection },
-     *   workers: [{
-     *     topic: 'order.process',
-     *     connection,
-     *     retryPolicy: {
-     *       maximumAttempts: 5,
-     *       backoffCoefficient: 2,
-     *       maximumInterval: '30s',
-     *     },
-     *     callback: async (data: StreamData) => {
-     *       const result = await doWork(data.data);
-     *       return {
-     *         code: 200,
-     *         status: StreamStatus.SUCCESS,
-     *         metadata: { ...data.metadata },
-     *         data: { result },
-     *       } as StreamDataResponse;
-     *     }
-     *   }]
-     * });
-     * ```
-     *
-     * **Retry Policy Options**:
-     * - `maximumAttempts` - Maximum retry attempts before failure (default: 3)
-     * - `backoffCoefficient` - Base for exponential backoff calculation (default: 10)
-     * - `maximumInterval` - Maximum delay between retries in seconds or duration string (default: '120s')
-     *
-     * **Retry Delays**: For `backoffCoefficient: 2`, delays are: 2s, 4s, 8s, 16s, 32s...
-     * capped at `maximumInterval`.
-     *
-     * **Note**: Retry policies are stored in PostgreSQL columns for efficient querying and
-     * observability. Each retry creates a new message, preserving message immutability.
+     * @param config - Engine connection, worker definitions, app ID, and options.
+     * @returns A running HotMesh instance joined to the quorum.
      */
     static async init(config) {
         const instance = new HotMesh();
@@ -289,9 +179,9 @@ class HotMesh {
         instance.verifyAndSetNamespace(config.namespace);
         instance.verifyAndSetAppId(config.appId);
         instance.logger = new logger_1.LoggerService(config.appId, instance.guid, config.name || '', config.logLevel);
-        await instance.initEngine(config, instance.logger);
-        await instance.initQuorum(config, instance.engine, instance.logger);
-        await instance.doWork(config, instance.logger);
+        await Init.initEngine(instance, config, instance.logger);
+        await Init.initQuorum(instance, config, instance.engine, instance.logger);
+        await Init.doWork(instance, config, instance.logger);
         return instance;
     }
     /**
@@ -301,624 +191,245 @@ class HotMesh {
     static guid() {
         return (0, utils_1.guid)();
     }
-    /**
-     * @private
-     */
-    async initEngine(config, logger) {
-        if (config.engine) {
-            //connections that are 'readonly' transfer
-            //this property directly to the engine,
-            //and ALWAYS take precendence.
-            if (config.engine.connection.readonly) {
-                config.engine.readonly = true;
-            }
-            // Apply retry policy to stream connection if provided
-            if (config.engine.retryPolicy) {
-                this.applyRetryPolicy(config.engine.connection, config.engine.retryPolicy);
-            }
-            // Initialize task queue for engine
-            config.engine.taskQueue = this.initTaskQueue(config.engine.taskQueue, config.taskQueue);
-            await factory_1.ConnectorService.initClients(config.engine);
-            this.engine = await engine_1.EngineService.init(this.namespace, this.appId, this.guid, config, logger);
-        }
-    }
-    /**
-     * @private
-     */
-    async initQuorum(config, engine, logger) {
-        if (engine) {
-            this.quorum = await quorum_1.QuorumService.init(this.namespace, this.appId, this.guid, config, engine, logger);
-        }
-    }
-    /**
-     * @private
-     */
-    constructor() {
-        /**
-         * @private
-         */
-        this.engine = null;
-        /**
-         * @private
-         */
-        this.quorum = null;
-        /**
-         * @private
-         */
-        this.workers = [];
-    }
-    /**
-     * @private
-     */
-    async doWork(config, logger) {
-        // Initialize task queues for workers
-        if (config.workers) {
-            for (const worker of config.workers) {
-                // Apply retry policy to stream connection if provided
-                if (worker.retryPolicy) {
-                    this.applyRetryPolicy(worker.connection, worker.retryPolicy);
-                }
-                worker.taskQueue = this.initTaskQueue(worker.taskQueue, config.taskQueue);
-            }
-        }
-        this.workers = await worker_1.WorkerService.init(this.namespace, this.appId, this.guid, config, logger);
-    }
-    /**
-     * Initialize task queue with proper precedence:
-     * 1. Use component-specific queue if set (engine/worker)
-     * 2. Use global config queue if set
-     * 3. Use default queue as fallback
-     * @private
-     */
-    initTaskQueue(componentQueue, globalQueue) {
-        // Component-specific queue takes precedence
-        if (componentQueue) {
-            return componentQueue;
-        }
-        // Global config queue is next
-        if (globalQueue) {
-            return globalQueue;
-        }
-        // Default queue as fallback
-        return enums_1.DEFAULT_TASK_QUEUE;
-    }
-    /**
-     * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
-     * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
-     * @private
-     */
-    applyRetryPolicy(connection, retryPolicy) {
-        // Check if this is ProvidersConfig (has 'stream' property)
-        if ('stream' in connection && connection.stream) {
-            // Long-form: apply to the stream sub-config
-            connection.stream.retryPolicy = retryPolicy;
-        }
-        else {
-            // Short-form: apply directly to the connection
-            connection.retryPolicy = retryPolicy;
-        }
-    }
     // ************* PUB/SUB METHODS *************
     /**
      * Publishes a message to a workflow topic, starting a new job.
-     * Returns the job ID immediately (fire-and-forget). Use `pubsub`
-     * to block until the workflow completes.
+     * Returns the job ID immediately (fire-and-forget).
      *
-     * @example
-     * ```typescript
-     * const jobId = await hotMesh.pub('order.placed', {
-     *   id: 'ORD-123',
-     *   amount: 99.99,
-     * });
-     * console.log(`Started job ${jobId}`);
-     * ```
+     * @param topic - The workflow topic (must match a deployed graph's `subscribes`).
+     * @param data - Input data for the workflow.
+     * @returns The new job ID.
      */
     async pub(topic, data = {}, context, extended) {
-        return await this.engine?.pub(topic, data, context, extended);
+        return PubSub.pub(this, topic, data, context, extended);
     }
     /**
-     * Subscribes to all output and interim emissions from a specific
-     * workflow topic. The callback fires each time a job on that topic
-     * completes or emits an interim result.
+     * Subscribes to all output and interim emissions from a workflow topic.
      *
-     * @example
-     * ```typescript
-     * await hotMesh.sub('order.fulfilled', (topic, message) => {
-     *   console.log(`Order completed:`, message.data);
-     * });
-     * ```
+     * @param topic - The topic to subscribe to.
+     * @param callback - Invoked with each job output or interim emission.
      */
     async sub(topic, callback) {
-        return await this.engine?.sub(topic, callback);
+        return PubSub.sub(this, topic, callback);
     }
     /**
-     * Unsubscribes from a single workflow topic previously registered
-     * with `sub()`.
+     * Unsubscribes from a workflow topic previously registered with {@link sub}.
      */
     async unsub(topic) {
-        return await this.engine?.unsub(topic);
+        return PubSub.unsub(this, topic);
     }
     /**
      * Subscribes to workflow emissions matching a wildcard pattern.
-     * Useful for monitoring an entire domain of workflows at once.
      *
-     * @example
-     * ```typescript
-     * // Listen to all order-related workflow completions
-     * await hotMesh.psub('order.*', (topic, message) => {
-     *   console.log(`${topic} completed:`, message.data);
-     * });
-     * ```
+     * @param wild - The wildcard pattern (e.g., `'order.*'`).
+     * @param callback - Invoked with each matching emission.
      */
     async psub(wild, callback) {
-        return await this.engine?.psub(wild, callback);
+        return PubSub.psub(this, wild, callback);
     }
     /**
-     * Unsubscribes from a wildcard pattern previously registered with `psub()`.
+     * Unsubscribes from a wildcard pattern previously registered with {@link psub}.
      */
     async punsub(wild) {
-        return await this.engine?.punsub(wild);
+        return PubSub.punsub(this, wild);
     }
     /**
-     * Publishes a message to a workflow topic and blocks until the workflow
-     * completes, returning the final job output. Internally subscribes to
-     * the workflow's `publishes` topic before publishing, then unsubscribes
-     * after receiving the result.
+     * Publishes a message and blocks until the workflow completes,
+     * returning the final job output. Combines {@link pub} + {@link sub}
+     * into a single request/response call.
      *
-     * @example
-     * ```typescript
-     * const result = await hotMesh.pubsub('order.placed', {
-     *   id: 'ORD-789',
-     *   amount: 49.99,
-     * });
-     * console.log('Order result:', result.data);
-     * ```
+     * @param topic - The workflow topic.
+     * @param data - Input data for the workflow.
+     * @param context - Optional job state context.
+     * @param timeout - Optional timeout in milliseconds.
+     * @returns The completed job output.
      */
     async pubsub(topic, data = {}, context, timeout) {
-        return await this.engine?.pubsub(topic, data, context, timeout);
+        return PubSub.pubsub(this, topic, data, context, timeout);
     }
     /**
      * Adds a transition message to the workstream, resuming Leg 2 of a
-     * paused reentrant activity (e.g., `await`, `worker`, `hook`). This
-     * is typically called by the engine internally but is exposed for
-     * advanced use cases like custom activity implementations.
+     * paused reentrant activity.
+     * @private
      */
     async add(streamData) {
-        return (await this.engine.add(streamData));
+        return PubSub.add(this, streamData);
     }
     // ************* QUORUM METHODS *************
     /**
-     * Broadcasts a roll call across the mesh and collects responses from
-     * every connected engine and worker. Each member replies with its
-     * `QuorumProfile` — including GUID, worker topic, stream depth,
-     * throttle rate, and system health (CPU, memory, network).
+     * Broadcasts a PING to all connected engines and workers via
+     * LISTEN/NOTIFY and collects their profiles. Returns one
+     * {@link QuorumProfile} per responding instance, including
+     * cumulative message `counts`, `error_count`, `stream_depth`,
+     * `throttle` state, and host-level `system` health (memory/CPU).
      *
-     * Use this for service discovery, health checks, and capacity planning.
+     * Use this for health checks, topology discovery, and throughput
+     * monitoring across the mesh.
      *
-     * @example
-     * ```typescript
-     * const members = await hotMesh.rollCall();
-     * for (const member of members) {
-     *   console.log(
-     *     `${member.engine_id} | topic=${member.worker_topic ?? 'engine'} ` +
-     *     `| throttle=${member.throttle}ms | depth=${member.stream_depth}`,
-     *   );
-     * }
-     * ```
+     * @param delay - Time in ms to wait for PONG responses (default: quorum config).
+     * @returns One profile per responding engine/worker instance.
      */
     async rollCall(delay) {
-        return await this.quorum?.rollCall(delay);
+        return Quorum.rollCall(this, delay);
     }
     /**
-     * Broadcasts a throttle command to the mesh via the quorum channel.
-     * Targeted members insert a delay (in milliseconds) before processing
-     * their next stream message, providing instant backpressure control
-     * across any combination of engines and workers.
-     *
-     * Throttling is **stateless** — no data is lost. Messages accumulate
-     * in Postgres streams and are processed once the throttle is lifted.
-     *
-     * ## Targeting
-     *
-     * | Option  | Effect |
-     * |---------|--------|
-     * | *(none)* | Throttle the **entire mesh** (all engines + all workers) |
-     * | `topic` | Throttle all workers subscribed to this topic |
-     * | `guid`  | Throttle a single engine or worker instance |
-     * | `topic` + `guid` | Throttle a specific topic on a specific instance |
-     *
-     * ## Special Values
-     *
-     * | Value  | Effect |
-     * |--------|--------|
-     * | `0`    | Resume normal processing (remove throttle) |
-     * | `-1`   | Pause indefinitely (emergency stop) |
-     * | `500`  | 500ms delay between messages |
+     * Broadcasts a throttle command to all instances. Use to slow down or
+     * pause message consumption across the mesh.
      *
-     * @example
-     * ```typescript
-     * // Emergency stop: pause the entire mesh
-     * await hotMesh.throttle({ throttle: -1 });
-     *
-     * // Resume the entire mesh
-     * await hotMesh.throttle({ throttle: 0 });
-     *
-     * // Slow a specific worker topic to 1 msg per second
-     * await hotMesh.throttle({ throttle: 1000, topic: 'order.process' });
-     *
-     * // Throttle a single instance by GUID
-     * await hotMesh.throttle({ throttle: 2000, guid: 'abc-123' });
-     *
-     * // Throttle a specific topic on a specific instance
-     * await hotMesh.throttle({
-     *   throttle: 500,
-     *   guid: 'abc-123',
-     *   topic: 'payment.charge',
-     * });
-     * ```
+     * @param options - Throttle rate in ms (0 = no throttle, -1 = pause indefinitely).
+     *   Optionally scope by `guid` (single instance) or `topic` (single worker).
      */
     async throttle(options) {
-        let throttle;
-        if (options.throttle === -1) {
-            throttle = enums_1.MAX_DELAY;
-        }
-        else {
-            throttle = options.throttle;
-        }
-        if (!Number.isInteger(throttle) || throttle < 0 || throttle > enums_1.MAX_DELAY) {
-            throw new Error(`Throttle must be a non-negative integer and not exceed ${enums_1.MAX_DELAY} ms; send -1 to throttle indefinitely`);
-        }
-        const throttleMessage = {
-            type: 'throttle',
-            throttle: throttle,
-        };
-        if (options.guid) {
-            throttleMessage.guid = options.guid;
-        }
-        if (options.topic !== undefined) {
-            throttleMessage.topic = options.topic;
-        }
-        await this.engine.store.setThrottleRate(throttleMessage);
-        return await this.quorum?.pub(throttleMessage);
+        return Quorum.throttle(this, options);
     }
     /**
-     * Publishes a message to every mesh member via the quorum channel
-     * (Postgres LISTEN/NOTIFY). Any `QuorumMessage` type can be sent,
-     * but the `user` type is the most common for application-level
-     * messaging.
-     *
-     * @example
-     * ```typescript
-     * // Broadcast a custom event to all mesh members
-     * await hotMesh.pubQuorum({
-     *   type: 'user',
-     *   topic: 'deploy.notify',
-     *   message: { version: '2.1.0', deployer: 'ci-pipeline' },
-     * });
-     *
-     * // Broadcast a config-reload signal
-     * await hotMesh.pubQuorum({
-     *   type: 'user',
-     *   topic: 'config.reload',
-     *   message: { features: { darkMode: true } },
-     * });
-     * ```
+     * Publishes a custom message to every instance via the quorum channel.
+     * Register a listener with {@link subQuorum} to receive these messages.
      */
     async pubQuorum(quorumMessage) {
-        return await this.quorum?.pub(quorumMessage);
+        return Quorum.pubQuorum(this, quorumMessage);
     }
     /**
-     * Subscribes to the quorum channel, receiving **every** message
-     * broadcast across the mesh in real time. This is the primary
-     * observability hook into the service mesh — use it to monitor
-     * version activations, throttle commands, roll call responses,
-     * workflow completions, and custom user events.
-     *
-     * Messages arrive as typed `QuorumMessage` unions. Switch on
-     * `message.type` to handle each:
-     *
-     * | Type        | When it fires |
-     * |-------------|---------------|
-     * | `pong`      | A mesh member responds to a roll call |
-     * | `throttle`  | A throttle command was broadcast |
-     * | `activate`  | A version activation is in progress |
-     * | `job`       | A workflow completed and published its result |
-     * | `user`      | A custom user message (via `pubQuorum`) |
-     * | `ping`      | A roll call was initiated |
-     * | `work`      | A work distribution event |
-     * | `cron`      | A cron/scheduled event |
-     *
-     * @example
-     * ```typescript
-     * // Build a real-time mesh dashboard
-     * await hotMesh.subQuorum((topic, message) => {
-     *   switch (message.type) {
-     *     case 'pong':
-     *       dashboard.updateMember(message.guid, {
-     *         topic: message.profile?.worker_topic,
-     *         throttle: message.profile?.throttle,
-     *         depth: message.profile?.stream_depth,
-     *         cpu: message.profile?.system?.CPULoad,
-     *       });
-     *       break;
-     *
-     *     case 'throttle':
-     *       dashboard.logThrottle(
-     *         message.throttle,
-     *         message.topic,
-     *         message.guid,
-     *       );
-     *       break;
-     *
-     *     case 'job':
-     *       dashboard.logCompletion(message.topic, message.job);
-     *       break;
-     *
-     *     case 'user':
-     *       dashboard.logUserEvent(message.topic, message.message);
-     *       break;
-     *   }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // React to custom deployment events
-     * await hotMesh.subQuorum((topic, message) => {
-     *   if (message.type === 'user' && message.topic === 'config.reload') {
-     *     reloadFeatureFlags(message.message);
-     *   }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Log all mesh activity for audit
-     * await hotMesh.subQuorum((topic, message) => {
-     *   auditLog.append({
-     *     timestamp: Date.now(),
-     *     type: message.type,
-     *     guid: message.guid,
-     *     topic: message.topic,
-     *     payload: message,
-     *   });
-     * });
-     * ```
+     * Subscribes to the quorum channel to receive system messages (version
+     * activations, throttle commands, roll calls) and custom user messages.
      */
     async subQuorum(callback) {
-        return await this.quorum?.sub(callback);
+        return Quorum.subQuorum(this, callback);
     }
     /**
-     * Unsubscribes a callback previously registered with `subQuorum()`.
+     * Unsubscribes a callback previously registered with {@link subQuorum}.
      */
     async unsubQuorum(callback) {
-        return await this.quorum?.unsub(callback);
+        return Quorum.unsubQuorum(this, callback);
     }
     // ************* LIFECYCLE METHODS *************
-    /**
-     * Preview changes and provide an analysis of risk
-     * prior to deployment
-     * @private
-     */
+    /** @private */
     async plan(path) {
-        return await this.engine?.plan(path);
+        return Deployment.plan(this, path);
     }
     /**
-     * Deploys a YAML workflow graph to Postgres. Accepts a file path or
-     * an inline YAML string. Referenced `$ref` files are resolved and
-     * merged. The deployed version is **inactive** until `activate()` is
-     * called.
-     *
-     * @example
-     * ```typescript
-     * // Deploy from an inline YAML string
-     * await hotMesh.deploy(`
-     * app:
-     *   id: myapp
-     *   version: '2'
-     *   graphs:
-     *     - subscribes: order.placed
-     *       activities:
-     *         t1:
-     *           type: trigger
-     *         process:
-     *           type: worker
-     *           topic: order.process
-     *       transitions:
-     *         t1:
-     *           - to: process
-     * `);
+     * Deploys a YAML workflow graph to Postgres. The graph is stored but
+     * remains **inactive** until {@link activate} is called.
      *
-     * // Deploy from a file path (resolves $ref references)
-     * await hotMesh.deploy('./workflows/order.yaml');
-     * ```
+     * @param pathOrYAML - A file path or raw YAML string defining the workflow graph.
+     * @returns The parsed manifest with version and graph metadata.
      */
     async deploy(pathOrYAML) {
-        return await this.engine?.deploy(pathOrYAML);
+        return Deployment.deploy(this, pathOrYAML);
     }
     /**
-     * Activates a deployed version across the entire mesh. The quorum
-     * coordinates a synchronized switch-over:
-     *
-     * 1. Roll call to verify quorum health.
-     * 2. Broadcast `nocache` mode — all engines consult Postgres for the
-     *    active version on every request.
-     * 3. Set the new version as active.
-     * 4. Broadcast `cache` mode — engines resume caching.
-     *
-     * The optional `delay` adds a pause (in ms) for the quorum to reach
-     * consensus under heavy traffic. Combine with `throttle()` for
-     * zero-downtime version switches.
-     *
-     * @example
-     * ```typescript
-     * // Simple activation
-     * await hotMesh.activate('2');
+     * Activates a previously deployed version across all connected instances.
+     * The quorum coordinates a synchronized version switch so every engine
+     * and worker transitions together.
      *
-     * // With consensus delay under heavy traffic
-     * await hotMesh.throttle({ throttle: 500 });   // slow the mesh
-     * await hotMesh.activate('2', 2000);            // activate with 2s consensus window
-     * await hotMesh.throttle({ throttle: 0 });      // resume full speed
-     * ```
+     * @param version - The version string to activate (must match a deployed graph).
+     * @param delay - Optional delay in ms before activation takes effect.
      */
     async activate(version, delay) {
-        return await this.quorum?.activate(version, delay);
+        return Deployment.activate(this, version, delay);
     }
+    // ************* JOB METHODS *************
     /**
-     * Exports the full job state as a structured JSON object, including
-     * activity data, transitions, and dependency chains. Useful for
-     * debugging, auditing, and visualizing workflow execution.
+     * Exports the full job state (data, metadata, activity results) as
+     * a structured JSON object.
+     *
+     * @param jobId - The job/workflow ID.
+     * @param options - Export options (e.g., include activity details).
      */
     async export(jobId, options = {}) {
-        return await this.engine?.export(jobId, options);
+        return Jobs.exportJob(this, jobId, options);
     }
     /**
-     * Returns all raw key-value pairs for a job's HASH record. This is
-     * the lowest-level read — it returns internal engine fields alongside
-     * user data. Prefer `getState()` for structured output.
+     * Returns all raw key-value pairs from a job's HASH record in Postgres.
+     * Useful for debugging or low-level inspection.
      */
     async getRaw(jobId) {
-        return await this.engine?.getRaw(jobId);
+        return Jobs.getRaw(this, jobId);
     }
-    /**
-     * Reporter-related method to get the status of a job
-     * @private
-     */
+    /** @private */
     async getStats(topic, query) {
-        return await this.engine?.getStats(topic, query);
+        return Jobs.getStats(this, topic, query);
     }
     /**
-     * Returns the numeric status semaphore for a job.
-     *
-     * | Value            | Meaning |
-     * |------------------|---------|
-     * | `> 0`            | Running (count of open activities) |
-     * | `0`              | Completed normally |
-     * | `-1`             | Pending (awaiting activation) |
-     * | `< -100,000,000` | Interrupted (abnormal termination) |
+     * Returns the numeric status code for a job: `0` = completed,
+     * positive = still running, negative = interrupted/errored.
      */
     async getStatus(jobId) {
-        return this.engine?.getStatus(jobId);
+        return Jobs.getStatus(this, jobId);
     }
     /**
-     * Returns the structured job state (data and metadata) for a job,
-     * scoped to the given workflow topic.
+     * Returns the structured job state (data + metadata). For a completed
+     * job this is the final output; for a running job it reflects the
+     * latest persisted state.
      *
-     * @example
-     * ```typescript
-     * const state = await hotMesh.getState('order.placed', jobId);
-     * console.log(state.data);     // workflow output data
-     * console.log(state.metadata); // jid, aid, timestamps, etc.
-     * ```
+     * @param topic - The workflow topic.
+     * @param jobId - The job/workflow ID.
      */
     async getState(topic, jobId) {
-        return this.engine?.getState(topic, jobId);
+        return Jobs.getState(this, topic, jobId);
     }
     /**
      * Returns specific searchable fields from a job's HASH record.
-     * Pass field names to retrieve; use `":"` to read the reserved
-     * status field.
      *
-     * @example
-     * ```typescript
-     * const fields = ['orderId', 'status', '":"'];
-     * const data = await hotMesh.getQueryState(jobId, fields);
-     * // => { orderId: 'ORD-123', status: 'paid', ':': '0' }
-     * ```
+     * @param jobId - The job/workflow ID.
+     * @param fields - The field names to retrieve.
      */
     async getQueryState(jobId, fields) {
-        return await this.engine?.getQueryState(jobId, fields);
+        return Jobs.getQueryState(this, jobId, fields);
     }
-    /**
-     * @private
-     */
+    /** @private */
     async getIds(topic, query, queryFacets = []) {
-        return await this.engine?.getIds(topic, query, queryFacets);
+        return Jobs.getIds(this, topic, query, queryFacets);
     }
-    /**
-     * @private
-     */
+    /** @private */
     async resolveQuery(topic, query) {
-        return await this.engine?.resolveQuery(topic, query);
+        return Jobs.resolveQuery(this, topic, query);
     }
     /**
-     * Interrupts (terminates) an active workflow job. The job's status is
-     * set to an error code indicating abnormal termination, and any pending
-     * activities or timers are cancelled.
+     * Immediately terminates a running job. The job is marked as
+     * interrupted and its HASH is expired. Unlike {@link cancel}, this
+     * does not give the workflow a chance to run cleanup code.
      *
-     * @example
-     * ```typescript
-     * await hotMesh.interrupt('order.placed', jobId, {
-     *   reason: 'Customer cancelled',
-     *   descend: true,   // also interrupt child workflows
-     * });
-     * ```
+     * @param topic - The workflow topic.
+     * @param jobId - The job/workflow ID.
+     * @param options - Optional interrupt configuration.
      */
     async interrupt(topic, jobId, options = {}) {
-        return await this.engine?.interrupt(topic, jobId, options);
+        return Jobs.interrupt(this, topic, jobId, options);
     }
     /**
-     * Immediately deletes a completed job from the system. The job must
-     * have a non-positive status (completed or interrupted). Running jobs
-     * must be interrupted first.
+     * Requests cooperative cancellation of a running job. Sets a durable
+     * cancel flag; the workflow detects it at its next durable operation
+     * and throws `CancelledFailure`, which can be caught for cleanup.
+     *
+     * @param jobId - The job/workflow ID.
      */
-    async scrub(jobId) {
-        await this.engine?.scrub(jobId);
+    async cancel(jobId) {
+        return Jobs.cancel(this, jobId);
     }
     /**
-     * Sends a signal to a paused workflow, resuming its execution.
-     * The `topic` must match a hook rule defined in the YAML graph's
-     * `hooks` section. The engine locates the exact activity and
-     * dimension for reentry based on the hook rule's match conditions.
-     *
-     * Use this to deliver external data (approval decisions, webhook
-     * payloads, partner responses) into a workflow that is sleeping
-     * on a hook activity or awaiting a `waitFor()` signal.
-     *
-     * @example
-     * ```typescript
-     * // Resume a paused approval workflow with external data
-     * await hotMesh.signal('order.approval', {
-     *   id: jobId,
-     *   approved: true,
-     *   reviewer: 'manager@example.com',
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Signal a Durable workflow waiting on waitFor('payment-received')
-     * await hotMesh.signal(`${appId}.wfs.signal`, {
-     *   id: 'payment-received',
-     *   data: { amount: 99.99, currency: 'USD' },
-     * });
-     * ```
+     * Immediately deletes a completed job's HASH record from Postgres.
      */
-    async signal(topic, data, status, code) {
-        return await this.engine?.signal(topic, data, status, code);
+    async scrub(jobId) {
+        return Jobs.scrub(this, jobId);
     }
     /**
-     * Fan-out variant of `signal()` that delivers data to **all**
-     * paused workflows matching a search query. Useful for resuming
-     * a batch of workflows waiting on the same external event.
+     * Sends a signal to a paused workflow, delivering data and resuming
+     * execution. Pairs with `condition()` in the Durable workflow API.
      *
-     * @private
+     * @param topic - The signal topic.
+     * @param data - Signal payload.
      */
+    async signal(topic, data, status, code) {
+        return Jobs.signal(this, topic, data, status, code);
+    }
+    /** @private */
     async signalAll(hookTopic, data, query, queryFacets = []) {
-        return await this.engine?.signalAll(hookTopic, data, query, queryFacets);
+        return Jobs.signalAll(this, hookTopic, data, query, queryFacets);
     }
+    // ************* STATIC LIFECYCLE *************
     /**
-     * Stops **all** HotMesh instances in the current process — engines,
-     * workers, and connections. Typically called in signal handlers
-     * (`SIGTERM`, `SIGINT`) for graceful shutdown.
-     *
-     * @example
-     * ```typescript
-     * process.on('SIGTERM', async () => {
-     *   await HotMesh.stop();
-     *   process.exit(0);
-     * });
-     * ```
+     * Stops **all** HotMesh instances in the current process.
      */
     static async stop() {
         if (!this.disconnecting) {
@@ -928,9 +439,8 @@ class HotMesh {
         }
     }
     /**
-     * Stops this specific HotMesh instance — its engine, quorum
-     * membership, and all attached workers. Other instances in the
-     * same process are unaffected.
+     * Stops this specific HotMesh instance — leaves the quorum and
+     * stops all workers. Does not affect other instances in the process.
      */
     stop() {
         this.engine?.taskService.cancelCleanup();
@@ -946,6 +456,45 @@ class HotMesh {
     async compress(terms) {
         return await this.engine?.compress(terms);
     }
+    // ************* CODEC *************
+    /**
+     * Register a global payload codec for encoding/decoding serialized
+     * object data at rest. Once registered, all object values flowing
+     * through the serializer are stored as `/b{encoded}` instead of
+     * `/s{json}`. Use this for encryption, compression, or custom encoding.
+     *
+     * The codec is global — it applies to all HotMesh and Durable instances
+     * in the process. Pass `null` to remove a previously registered codec.
+     *
+     * **Constraints:** The codec must be synchronous and its output must be
+     * a valid UTF-8 string. Use base64 encoding for binary output.
+     *
+     * @example
+     * ```typescript
+     * import { HotMesh } from '@hotmeshio/hotmesh';
+     *
+     * HotMesh.registerCodec({
+     *   encode(json) { return Buffer.from(json).toString('base64'); },
+     *   decode(encoded) { return Buffer.from(encoded, 'base64').toString('utf8'); },
+     * });
+     * ```
+     */
+    static registerCodec(codec) {
+        serializer_1.SerializerService.registerCodec(codec);
+    }
 }
 exports.HotMesh = HotMesh;
 HotMesh.disconnecting = false;
+// ************* WORKER CREDENTIALS *************
+/**
+ * Provision a scoped Postgres role for a worker. The role can only
+ * dequeue, ack, and respond on its assigned stream names via stored
+ * procedures — zero direct table access.
+ */
+HotMesh.provisionWorkerRole = WorkerCredentials.provisionWorkerRole;
+/** Rotate a secured worker role's password. */
+HotMesh.rotateWorkerPassword = WorkerCredentials.rotateWorkerPassword;
+/** Revoke a secured worker role (disables login). */
+HotMesh.revokeWorkerRole = WorkerCredentials.revokeWorkerRole;
+/** List all provisioned secured worker roles. */
+HotMesh.listWorkerRoles = WorkerCredentials.listWorkerRoles;