@hotmeshio/hotmesh 0.12.1 → 0.14.0

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

@@ -9,6 +9,9 @@ import { JobMessageCallback, QuorumMessage, QuorumMessageCallback, QuorumProfile
 import { StringAnyType, StringStringType } from '../../types/serializer';
 import { JobStatsInput, GetStatsOptions, IdsResponse, StatsResponse } from '../../types/stats';
 import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../types/stream';
+import type { PayloadCodec } from '../../types/codec';
+import * as WorkerCredentials from '../worker/credentials';
+import type { WorkerCredential, WorkerCredentialInfo } from '../worker/credentials';
 /**
  * A distributed service mesh that turns Postgres into a durable workflow
  * orchestration engine. Every `HotMesh.init()` call creates a **point of
@@ -88,67 +91,6 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * 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.
@@ -160,7 +102,7 @@ import { StreamCode, StreamData, StreamDataResponse, StreamStatus } from '../../
  * ## 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
@@ -183,6 +125,10 @@ declare class HotMesh {
     workers: WorkerService[];
     logger: ILogger;
     static disconnecting: boolean;
+    /**
+     * @private
+     */
+    constructor();
     /**
      * @private
      */
@@ -192,92 +138,14 @@ declare class HotMesh {
      */
     verifyAndSetAppId(appId: string): void;
     /**
-     * Instance initializer. Workers are configured
-     * similarly to the engine, but as an array with
-     * multiple worker objects.
-     *
-     * ## Retry Policy Configuration
-     *
-     * 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.
+     * Create a HotMesh instance with an engine and optional workers.
      *
-     * - **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.
+     * 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.
      *
-     * @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 init(config: HotMeshConfig): Promise<HotMesh>;
     /**
@@ -285,485 +153,189 @@ declare class HotMesh {
      * internally by HotMesh for job IDs and GUIDs.
      */
     static guid(): string;
-    /**
-     * @private
-     */
-    initEngine(config: HotMeshConfig, logger: ILogger): Promise<void>;
-    /**
-     * @private
-     */
-    initQuorum(config: HotMeshConfig, engine: EngineService, logger: ILogger): Promise<void>;
-    /**
-     * @private
-     */
-    constructor();
-    /**
-     * @private
-     */
-    doWork(config: HotMeshConfig, logger: ILogger): Promise<void>;
-    /**
-     * 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
-     */
-    private initTaskQueue;
-    /**
-     * Apply retry policy to the stream connection within a ProviderConfig or ProvidersConfig.
-     * Handles both short-form (ProviderConfig) and long-form (ProvidersConfig) connection configs.
-     * @private
-     */
-    private applyRetryPolicy;
     /**
      * 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.
      */
     pub(topic: string, data?: JobData, context?: JobState, extended?: ExtensionType): Promise<string>;
     /**
-     * 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.
      */
     sub(topic: string, callback: JobMessageCallback): Promise<void>;
     /**
-     * Unsubscribes from a single workflow topic previously registered
-     * with `sub()`.
+     * Unsubscribes from a workflow topic previously registered with {@link sub}.
      */
     unsub(topic: string): Promise<void>;
     /**
      * 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.
      */
     psub(wild: string, callback: JobMessageCallback): Promise<void>;
     /**
-     * Unsubscribes from a wildcard pattern previously registered with `psub()`.
+     * Unsubscribes from a wildcard pattern previously registered with {@link psub}.
      */
     punsub(wild: string): Promise<void>;
     /**
-     * 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.
      */
     pubsub(topic: string, data?: JobData, context?: JobState | null, timeout?: number): Promise<JobOutput>;
     /**
      * 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
      */
     add(streamData: StreamData | StreamDataResponse): Promise<string>;
     /**
-     * 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.
      */
     rollCall(delay?: number): Promise<QuorumProfile[]>;
     /**
-     * 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).
      */
     throttle(options: ThrottleOptions): Promise<boolean>;
     /**
-     * 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.
      */
     pubQuorum(quorumMessage: QuorumMessage): Promise<boolean>;
     /**
-     * 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.
      */
     subQuorum(callback: QuorumMessageCallback): Promise<void>;
     /**
-     * Unsubscribes a callback previously registered with `subQuorum()`.
+     * Unsubscribes a callback previously registered with {@link subQuorum}.
      */
     unsubQuorum(callback: QuorumMessageCallback): Promise<void>;
-    /**
-     * Preview changes and provide an analysis of risk
-     * prior to deployment
-     * @private
-     */
+    /** @private */
     plan(path: string): Promise<HotMeshManifest>;
     /**
-     * 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.
      */
     deploy(pathOrYAML: string): Promise<HotMeshManifest>;
     /**
-     * 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.
+     * Activates a previously deployed version across all connected instances.
+     * The quorum coordinates a synchronized version switch so every engine
+     * and worker transitions together.
      *
-     * 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');
-     *
-     * // 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.
      */
     activate(version: string, delay?: number): Promise<boolean>;
     /**
-     * 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).
      */
     export(jobId: string, options?: ExportOptions): Promise<JobExport>;
     /**
-     * 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.
      */
     getRaw(jobId: string): Promise<StringStringType>;
-    /**
-     * Reporter-related method to get the status of a job
-     * @private
-     */
+    /** @private */
     getStats(topic: string, query: JobStatsInput): Promise<StatsResponse>;
     /**
-     * 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.
      */
     getStatus(jobId: string): Promise<JobStatus>;
     /**
-     * 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.
      */
     getState(topic: string, jobId: string): Promise<JobOutput>;
     /**
      * 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.
      */
     getQueryState(jobId: string, fields: string[]): Promise<StringAnyType>;
-    /**
-     * @private
-     */
+    /** @private */
     getIds(topic: string, query: JobStatsInput, queryFacets?: any[]): Promise<IdsResponse>;
-    /**
-     * @private
-     */
+    /** @private */
     resolveQuery(topic: string, query: JobStatsInput): Promise<GetStatsOptions>;
     /**
-     * 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.
      */
     interrupt(topic: string, jobId: string, options?: JobInterruptOptions): Promise<string>;
     /**
-     * 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.
      */
-    scrub(jobId: string): Promise<void>;
+    cancel(jobId: string): Promise<void>;
     /**
-     * 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.
      */
-    signal(topic: string, data: JobData, status?: StreamStatus, code?: StreamCode): Promise<string>;
+    scrub(jobId: string): Promise<void>;
     /**
-     * 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.
      */
+    signal(topic: string, data: JobData, status?: StreamStatus, code?: StreamCode): Promise<string>;
+    /** @private */
     signalAll(hookTopic: string, data: JobData, query: JobStatsInput, queryFacets?: string[]): Promise<string[]>;
     /**
-     * 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 stop(): Promise<void>;
     /**
-     * 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(): void;
     /**
@@ -771,5 +343,42 @@ declare class HotMesh {
      * @deprecated
      */
     compress(terms: string[]): Promise<boolean>;
+    /**
+     * 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: PayloadCodec | null): void;
+    /**
+     * 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.
+     */
+    static provisionWorkerRole: typeof WorkerCredentials.provisionWorkerRole;
+    /** Rotate a secured worker role's password. */
+    static rotateWorkerPassword: typeof WorkerCredentials.rotateWorkerPassword;
+    /** Revoke a secured worker role (disables login). */
+    static revokeWorkerRole: typeof WorkerCredentials.revokeWorkerRole;
+    /** List all provisioned secured worker roles. */
+    static listWorkerRoles: typeof WorkerCredentials.listWorkerRoles;
 }
 export { HotMesh };
+export type { PayloadCodec };
+export type { WorkerCredential, WorkerCredentialInfo };