@hotmeshio/hotmesh 0.14.9 → 0.15.1

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.14.9",
+    "version": "0.15.1",
     "description": "Durable Workflow",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",

package/build/services/durable/exporter.d.ts

@@ -41,6 +41,32 @@ declare function isSystemActivity(name: string): boolean;
  * both the `done` flag and the semaphore to determine status.
  */
 declare function mapStatus(rawStatus: number | undefined, isDone?: boolean, hasError?: boolean): WorkflowExecutionStatus;
+/**
+ * Exports durable workflow execution data in two formats:
+ *
+ * ### Raw export (`export()`)
+ * Returns a {@link DurableJobExport} with five sections:
+ * - **data** — workflow input arguments (what was passed to `workflow.start()`)
+ * - **state** — current workflow state: `done` flag, `response`, `$error`, timestamps (`jc`/`ju`)
+ * - **status** — HotMesh semaphore (`0` = complete, `> 0` = activities pending, `< 0` = failed)
+ * - **timeline** — ordered list of idempotent operations: proxy activities, child workflows,
+ *   sleeps, signals, and collated (Promise.all) results with per-entry timing and output
+ * - **transitions** — activity execution log with `created`/`updated` timestamps per dimension
+ *
+ * Use `allow`/`block` options to limit which sections are returned (e.g., omit
+ * `transitions` to reduce payload size). Use `values: false` to strip result
+ * payloads from timeline entries.
+ *
+ * ### Execution history (`exportExecution()`)
+ * Returns a {@link WorkflowExecution} — a Temporal-style event history with
+ * typed events (`activity_task_scheduled`, `timer_fired`, `workflow_execution_signaled`, etc.),
+ * chronological ordering, back-references between scheduled/completed pairs, and a summary
+ * with activity/child/timer/signal counts.
+ *
+ * Supports **sparse** mode (default, no extra I/O) and **verbose** mode (recursively
+ * fetches child workflow histories up to `max_depth`). Use `enrich_inputs` to attach
+ * activity and child workflow input arguments to events.
+ */
 declare class ExporterService {
     appId: string;
     logger: ILogger;
@@ -49,18 +75,72 @@ declare class ExporterService {
     private static symbols;
     constructor(appId: string, store: StoreService<ProviderClient, ProviderTransaction>, logger: ILogger);
     /**
-     * Convert the job hash from its compiled format into a DurableJobExport object with
-     * facets that describe the workflow in terms relevant to narrative storytelling.
+     * Export the raw workflow job as a structured {@link DurableJobExport}.
+     *
+     * The result contains five sections (filterable via `options.allow` / `options.block`):
+     *
+     * | Section | Contents |
+     * |---|---|
+     * | `data` | Workflow input arguments passed to `workflow.start()` |
+     * | `state` | Current state: `done`, `response`, `$error`, timestamps |
+     * | `status` | Semaphore value: `0` = idle, `> 0` = pending, `< 0` = error |
+     * | `timeline` | Ordered idempotent markers: activities, children, sleeps, signals |
+     * | `transitions` | Per-activity execution timestamps by dimension |
+     *
+     * @param jobId - the workflow ID to export
+     * @param options - controls which sections to include and whether to include values
+     * @returns the exported workflow data
+     *
+     * @example
+     * ```typescript
+     * // Full export
+     * const full = await handle.export();
+     *
+     * // Timeline only, without result payloads (smaller response)
+     * const slim = await handle.export({ allow: ['timeline'], values: false });
+     * ```
      */
     export(jobId: string, options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Export a workflow execution as a structured event history.
+     * Export a workflow execution as a structured event history ({@link WorkflowExecution}).
+     *
+     * Returns a Temporal-style event list with typed events, chronological ordering,
+     * back-references (e.g., `scheduled_event_id` on completed activities), and a
+     * {@link WorkflowExecutionSummary} with counts by category.
+     *
+     * **Event types produced:**
+     * - `workflow_execution_started` / `completed` / `failed` — lifecycle bookends
+     * - `activity_task_scheduled` / `completed` / `failed` — proxy activity calls
+     * - `child_workflow_execution_started` / `completed` / `failed` — child workflows
+     * - `timer_started` / `timer_fired` — `workflow.sleep()` calls
+     * - `workflow_execution_signaled` — `workflow.condition()` signals received
+     *
+     * **Modes:**
+     * - `sparse` (default) — transforms the workflow's timeline markers into events.
+     *   No extra database queries beyond the initial job export.
+     * - `verbose` — recursively fetches child workflow jobs and attaches their full
+     *   event histories as nested `children` (up to `max_depth`, default 5).
+     *
+     * **Options:**
+     * - `exclude_system` — omit internal/interceptor activities (names starting with `lt`)
+     * - `omit_results` — strip `result` and `input` payloads from event attributes
+     * - `enrich_inputs` — attach activity/child workflow input arguments to events
+     * - `allow_direct_query` — fallback to raw DB queries for expired/pruned jobs
      *
-     * **Sparse mode** (default): transforms the main workflow's timeline
-     * into a flat event list. No additional I/O beyond the initial export.
+     * @param jobId - the workflow ID
+     * @param workflowTopic - the task queue topic (used as `workflow_type`)
+     * @param options - controls mode, filtering, and enrichment
      *
-     * **Verbose mode**: recursively fetches child workflow jobs and attaches
-     * their executions as nested `children`.
+     * @example
+     * ```typescript
+     * // Sparse export with system activities filtered out
+     * const exec = await handle.exportExecution({ exclude_system: true });
+     * console.log(exec.summary.activities.user); // user activity count
+     *
+     * // Verbose export with full child workflow trees
+     * const deep = await handle.exportExecution({ mode: 'verbose', max_depth: 3 });
+     * console.log(deep.children); // nested WorkflowExecution[]
+     * ```
      */
     exportExecution(jobId: string, workflowTopic: string, options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**
@@ -88,10 +168,22 @@ declare class ExporterService {
      */
     private fetchChildren;
     /**
-     * Inflates the job data into a DurableJobExport object
-     * @param jobHash - the job data
-     * @param dependencyList - the list of dependencies for the job
-     * @returns - the inflated job data
+     * Inflate a raw Redis/Postgres job hash into a structured {@link DurableJobExport}.
+     *
+     * HotMesh stores workflow state as a flat hash with 3-character symbolized keys
+     * (e.g., `aBC,0,0` → `worker/output/data`). This method decodes each entry and
+     * sorts it into one of four buckets:
+     *
+     * - **Transitions** (`aBC,0,0` pattern) — activity start/stop timestamps by dimension
+     * - **Data** (`_`-prefixed keys) — workflow input arguments
+     * - **Timeline** (`-`-prefixed keys) — idempotent operation markers (proxy, child, sleep, etc.)
+     * - **State** (3-char keys) — workflow metadata (done flag, response, error, timestamps)
+     *
+     * Use `options.allow` / `options.block` to limit which sections appear in the result.
+     *
+     * @param jobHash - the raw key-value hash from the store
+     * @param options - filtering and value options
+     * @returns structured export with data, state, status, timeline, and transitions
      */
     inflate(jobHash: StringStringType, options: ExportOptions): DurableJobExport;
     resolveValue(raw: string, withValues: boolean): Record<string, any> | string | number | null;

package/build/services/durable/exporter.js

@@ -153,6 +153,32 @@ function computeSummary(events) {
     return summary;
 }
 // ── Exporter Service ─────────────────────────────────────────────────────────
+/**
+ * Exports durable workflow execution data in two formats:
+ *
+ * ### Raw export (`export()`)
+ * Returns a {@link DurableJobExport} with five sections:
+ * - **data** — workflow input arguments (what was passed to `workflow.start()`)
+ * - **state** — current workflow state: `done` flag, `response`, `$error`, timestamps (`jc`/`ju`)
+ * - **status** — HotMesh semaphore (`0` = complete, `> 0` = activities pending, `< 0` = failed)
+ * - **timeline** — ordered list of idempotent operations: proxy activities, child workflows,
+ *   sleeps, signals, and collated (Promise.all) results with per-entry timing and output
+ * - **transitions** — activity execution log with `created`/`updated` timestamps per dimension
+ *
+ * Use `allow`/`block` options to limit which sections are returned (e.g., omit
+ * `transitions` to reduce payload size). Use `values: false` to strip result
+ * payloads from timeline entries.
+ *
+ * ### Execution history (`exportExecution()`)
+ * Returns a {@link WorkflowExecution} — a Temporal-style event history with
+ * typed events (`activity_task_scheduled`, `timer_fired`, `workflow_execution_signaled`, etc.),
+ * chronological ordering, back-references between scheduled/completed pairs, and a summary
+ * with activity/child/timer/signal counts.
+ *
+ * Supports **sparse** mode (default, no extra I/O) and **verbose** mode (recursively
+ * fetches child workflow histories up to `max_depth`). Use `enrich_inputs` to attach
+ * activity and child workflow input arguments to events.
+ */
 class ExporterService {
     constructor(appId, store, logger) {
         this.appId = appId;
@@ -160,8 +186,30 @@ class ExporterService {
         this.store = store;
     }
     /**
-     * Convert the job hash from its compiled format into a DurableJobExport object with
-     * facets that describe the workflow in terms relevant to narrative storytelling.
+     * Export the raw workflow job as a structured {@link DurableJobExport}.
+     *
+     * The result contains five sections (filterable via `options.allow` / `options.block`):
+     *
+     * | Section | Contents |
+     * |---|---|
+     * | `data` | Workflow input arguments passed to `workflow.start()` |
+     * | `state` | Current state: `done`, `response`, `$error`, timestamps |
+     * | `status` | Semaphore value: `0` = idle, `> 0` = pending, `< 0` = error |
+     * | `timeline` | Ordered idempotent markers: activities, children, sleeps, signals |
+     * | `transitions` | Per-activity execution timestamps by dimension |
+     *
+     * @param jobId - the workflow ID to export
+     * @param options - controls which sections to include and whether to include values
+     * @returns the exported workflow data
+     *
+     * @example
+     * ```typescript
+     * // Full export
+     * const full = await handle.export();
+     *
+     * // Timeline only, without result payloads (smaller response)
+     * const slim = await handle.export({ allow: ['timeline'], values: false });
+     * ```
      */
     async export(jobId, options = {}) {
         if (!ExporterService.symbols.has(this.appId)) {
@@ -173,13 +221,45 @@ class ExporterService {
         return jobExport;
     }
     /**
-     * Export a workflow execution as a structured event history.
+     * Export a workflow execution as a structured event history ({@link WorkflowExecution}).
+     *
+     * Returns a Temporal-style event list with typed events, chronological ordering,
+     * back-references (e.g., `scheduled_event_id` on completed activities), and a
+     * {@link WorkflowExecutionSummary} with counts by category.
+     *
+     * **Event types produced:**
+     * - `workflow_execution_started` / `completed` / `failed` — lifecycle bookends
+     * - `activity_task_scheduled` / `completed` / `failed` — proxy activity calls
+     * - `child_workflow_execution_started` / `completed` / `failed` — child workflows
+     * - `timer_started` / `timer_fired` — `workflow.sleep()` calls
+     * - `workflow_execution_signaled` — `workflow.condition()` signals received
+     *
+     * **Modes:**
+     * - `sparse` (default) — transforms the workflow's timeline markers into events.
+     *   No extra database queries beyond the initial job export.
+     * - `verbose` — recursively fetches child workflow jobs and attaches their full
+     *   event histories as nested `children` (up to `max_depth`, default 5).
+     *
+     * **Options:**
+     * - `exclude_system` — omit internal/interceptor activities (names starting with `lt`)
+     * - `omit_results` — strip `result` and `input` payloads from event attributes
+     * - `enrich_inputs` — attach activity/child workflow input arguments to events
+     * - `allow_direct_query` — fallback to raw DB queries for expired/pruned jobs
      *
-     * **Sparse mode** (default): transforms the main workflow's timeline
-     * into a flat event list. No additional I/O beyond the initial export.
+     * @param jobId - the workflow ID
+     * @param workflowTopic - the task queue topic (used as `workflow_type`)
+     * @param options - controls mode, filtering, and enrichment
      *
-     * **Verbose mode**: recursively fetches child workflow jobs and attaches
-     * their executions as nested `children`.
+     * @example
+     * ```typescript
+     * // Sparse export with system activities filtered out
+     * const exec = await handle.exportExecution({ exclude_system: true });
+     * console.log(exec.summary.activities.user); // user activity count
+     *
+     * // Verbose export with full child workflow trees
+     * const deep = await handle.exportExecution({ mode: 'verbose', max_depth: 3 });
+     * console.log(deep.children); // nested WorkflowExecution[]
+     * ```
      */
     async exportExecution(jobId, workflowTopic, options = {}) {
         let execution;
@@ -845,10 +925,22 @@ class ExporterService {
         return children;
     }
     /**
-     * Inflates the job data into a DurableJobExport object
-     * @param jobHash - the job data
-     * @param dependencyList - the list of dependencies for the job
-     * @returns - the inflated job data
+     * Inflate a raw Redis/Postgres job hash into a structured {@link DurableJobExport}.
+     *
+     * HotMesh stores workflow state as a flat hash with 3-character symbolized keys
+     * (e.g., `aBC,0,0` → `worker/output/data`). This method decodes each entry and
+     * sorts it into one of four buckets:
+     *
+     * - **Transitions** (`aBC,0,0` pattern) — activity start/stop timestamps by dimension
+     * - **Data** (`_`-prefixed keys) — workflow input arguments
+     * - **Timeline** (`-`-prefixed keys) — idempotent operation markers (proxy, child, sleep, etc.)
+     * - **State** (3-char keys) — workflow metadata (done flag, response, error, timestamps)
+     *
+     * Use `options.allow` / `options.block` to limit which sections appear in the result.
+     *
+     * @param jobHash - the raw key-value hash from the store
+     * @param options - filtering and value options
+     * @returns structured export with data, state, status, timeline, and transitions
      */
     inflate(jobHash, options) {
         const timeline = [];

package/build/services/durable/handle.d.ts

@@ -37,19 +37,51 @@ export declare class WorkflowHandleService {
      */
     constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string);
     /**
-     * Exports the full workflow state (job hash, metadata, activity
-     * results) as a JSON object.
+     * Export the raw workflow state as a {@link DurableJobExport} with five sections:
+     *
+     * - **data** — workflow input arguments
+     * - **state** — done flag, response, error, timestamps
+     * - **status** — semaphore (`0` = complete, `> 0` = pending, `< 0` = error)
+     * - **timeline** — ordered idempotent markers for activities, children, sleeps, signals
+     * - **transitions** — per-activity execution timestamps by dimension
+     *
+     * Use `allow` / `block` to limit sections and `values: false` to strip payloads.
+     *
+     * @example
+     * ```typescript
+     * const raw = await handle.export();
+     * console.log(raw.state);    // { done: true, response: '...' }
+     * console.log(raw.timeline); // [{ key: '-proxy-1-', value: {...} }, ...]
+     *
+     * // Lightweight export: timeline keys only, no payloads
+     * const slim = await handle.export({ allow: ['timeline'], values: false });
+     * ```
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Exports the workflow as an execution event history.
+     * Export the workflow as a structured event history ({@link WorkflowExecution}).
      *
-     * **Sparse mode** (default): transforms the main workflow's timeline
-     * into a flat event list with workflow lifecycle, activity, child workflow,
-     * timer, and signal events.
+     * Returns a chronologically ordered event list with Temporal-style typed events,
+     * back-references between scheduled/completed pairs, and a summary with counts.
      *
-     * **Verbose mode**: recursively fetches child workflow jobs and attaches
-     * their full execution histories as nested `children`.
+     * **Event types:** `activity_task_scheduled/completed/failed`,
+     * `child_workflow_execution_started/completed/failed`, `timer_started/fired`,
+     * `workflow_execution_started/completed/failed/signaled`
+     *
+     * **Modes:**
+     * - `sparse` (default) — single query, transforms timeline markers into events
+     * - `verbose` — recursively fetches child workflows as nested `children`
+     *
+     * **Options:** `exclude_system`, `omit_results`, `enrich_inputs`, `allow_direct_query`
+     *
+     * @example
+     * ```typescript
+     * const exec = await handle.exportExecution({ exclude_system: true });
+     * for (const event of exec.events) {
+     *   console.log(event.event_type, event.attributes);
+     * }
+     * console.log(exec.summary); // { activities: { total: 5, ... }, timers: 1, ... }
+     * ```
      */
     exportExecution(options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**

package/build/services/durable/handle.js

@@ -34,21 +34,53 @@ class WorkflowHandleService {
         this.exporter = new exporter_1.ExporterService(this.hotMesh.appId, this.hotMesh.engine.store, this.hotMesh.engine.logger);
     }
     /**
-     * Exports the full workflow state (job hash, metadata, activity
-     * results) as a JSON object.
+     * Export the raw workflow state as a {@link DurableJobExport} with five sections:
+     *
+     * - **data** — workflow input arguments
+     * - **state** — done flag, response, error, timestamps
+     * - **status** — semaphore (`0` = complete, `> 0` = pending, `< 0` = error)
+     * - **timeline** — ordered idempotent markers for activities, children, sleeps, signals
+     * - **transitions** — per-activity execution timestamps by dimension
+     *
+     * Use `allow` / `block` to limit sections and `values: false` to strip payloads.
+     *
+     * @example
+     * ```typescript
+     * const raw = await handle.export();
+     * console.log(raw.state);    // { done: true, response: '...' }
+     * console.log(raw.timeline); // [{ key: '-proxy-1-', value: {...} }, ...]
+     *
+     * // Lightweight export: timeline keys only, no payloads
+     * const slim = await handle.export({ allow: ['timeline'], values: false });
+     * ```
      */
     async export(options) {
         return this.exporter.export(this.workflowId, options);
     }
     /**
-     * Exports the workflow as an execution event history.
+     * Export the workflow as a structured event history ({@link WorkflowExecution}).
      *
-     * **Sparse mode** (default): transforms the main workflow's timeline
-     * into a flat event list with workflow lifecycle, activity, child workflow,
-     * timer, and signal events.
+     * Returns a chronologically ordered event list with Temporal-style typed events,
+     * back-references between scheduled/completed pairs, and a summary with counts.
      *
-     * **Verbose mode**: recursively fetches child workflow jobs and attaches
-     * their full execution histories as nested `children`.
+     * **Event types:** `activity_task_scheduled/completed/failed`,
+     * `child_workflow_execution_started/completed/failed`, `timer_started/fired`,
+     * `workflow_execution_started/completed/failed/signaled`
+     *
+     * **Modes:**
+     * - `sparse` (default) — single query, transforms timeline markers into events
+     * - `verbose` — recursively fetches child workflows as nested `children`
+     *
+     * **Options:** `exclude_system`, `omit_results`, `enrich_inputs`, `allow_direct_query`
+     *
+     * @example
+     * ```typescript
+     * const exec = await handle.exportExecution({ exclude_system: true });
+     * for (const event of exec.events) {
+     *   console.log(event.event_type, event.attributes);
+     * }
+     * console.log(exec.summary); // { activities: { total: 5, ... }, timers: 1, ... }
+     * ```
      */
     async exportExecution(options) {
         return this.exporter.exportExecution(this.workflowId, this.workflowTopic, options);

package/build/services/durable/schemas/factory.d.ts

@@ -1,4 +1,4 @@
-declare const APP_VERSION = "12";
+declare const APP_VERSION = "13";
 declare const APP_ID = "durable";
 /**
  * returns a new durable workflow schema

package/build/services/durable/schemas/factory.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APP_ID = exports.APP_VERSION = exports.getWorkflowYAML = void 0;
-const APP_VERSION = '12';
+const APP_VERSION = '13';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'durable';
 exports.APP_ID = APP_ID;
@@ -136,10 +136,6 @@ const getWorkflowYAML = (app, version) => {
             maps:
               retryCount: 0
 
-        throttler:
-          title: Pass-through hook between cycle_hook and worker
-          type: hook
-
         worker:
           title: Main Worker - Calls linked Workflow functions
           type: worker
@@ -895,10 +891,6 @@ const getWorkflowYAML = (app, version) => {
             maps:
               retryCount: 0
 
-        signaler_throttler:
-          title: Pass-through hook between signaler_cycle_hook and signaler_worker
-          type: hook
-
         signaler_worker:
           title: Signal In - Worker
           type: worker
@@ -1531,8 +1523,6 @@ const getWorkflowYAML = (app, version) => {
                       - ['{@conditional.nullish}']
         ## MAIN PROCESS TRANSITIONS ##
         cycle_hook:
-          - to: throttler
-        throttler:
           - to: worker
         worker:
           - to: ender
@@ -1605,8 +1595,6 @@ const getWorkflowYAML = (app, version) => {
             conditions:
               code: 202
         signaler_cycle_hook:
-          - to: signaler_throttler
-        signaler_throttler:
           - to: signaler_worker
         signaler_worker:
           - to: signaler_sleeper

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

@@ -4,8 +4,25 @@ import { ActivityDetail, DependencyExport, ExportOptions, JobActionExport, JobEx
 import { ProviderClient, ProviderTransaction } from '../../types/provider';
 import { StringAnyType, StringStringType, Symbols } from '../../types/serializer';
 /**
- * Downloads job data and expands process data and
- * includes dependency list
+ * System-level exporter for HotMesh job data. Decodes the flat, symbolized
+ * hash stored in Redis/Postgres into a human-readable {@link JobExport}
+ * with three sections:
+ *
+ * - **process** — a nested object reflecting the activity execution tree.
+ *   Each activity's input, output, and metadata are organized by their
+ *   dimensional path (e.g., `0/0/worker/output/data`).
+ * - **dependencies** — list of dependent jobs (child workflows, hooks, signals)
+ *   spawned during execution.
+ * - **status** — the raw semaphore value from the job hash.
+ *
+ * Optionally, set `enrich_inputs: true` to produce a flat `activities` array
+ * ({@link ActivityDetail}[]) that merges stream message history (inputs, timing,
+ * retries) with process outputs — useful for dashboards and debugging views.
+ *
+ * @remarks
+ * This is the lower-level exporter used by the HotMesh engine directly.
+ * For durable workflow exports, use the `ExporterService` in `services/durable/exporter`
+ * which produces structured timeline and execution history formats.
  */
 declare class ExporterService {
     appId: string;
@@ -16,22 +33,39 @@ declare class ExporterService {
     /** @hidden */
     constructor(appId: string, store: StoreService<ProviderClient, ProviderTransaction>, logger: ILogger);
     /**
-     * Convert the job hash into a JobExport object.
-     * This object contains various facets that describe the interaction
-     * in terms relevant to narrative storytelling.
+     * Export a job as a structured {@link JobExport}.
+     *
+     * Reads the raw job hash from the store, inflates symbolized keys into
+     * readable paths, and organizes data into `process`, `dependencies`,
+     * and `status` sections.
+     *
+     * When `enrich_inputs` is true, also fetches stream message history and
+     * produces a flat `activities` array with per-activity input/output,
+     * timing, retry attempts, and cycle iteration info.
+     *
+     * @param jobId - the job ID to export
+     * @param options - controls enrichment behavior
      */
     export(jobId: string, options?: ExportOptions): Promise<JobExport>;
     /**
-     * Inflates the key
-     * into a human-readable JSON path, reflecting the
-     * tree-like structure of the unidimensional Hash
+     * Resolve a 3-character symbol key to its full path (e.g., `aBC` → `worker/output/data`).
+     * Returns the key unchanged if no symbol mapping exists.
      */
     inflateKey(key: string): string;
     /**
-     * Inflates the job data into a JobExport object
-     * @param jobHash - the job data
-     * @param dependencyList - the list of dependencies for the job
-     * @returns - the inflated job data
+     * Decode a raw job hash into a structured {@link JobExport}.
+     *
+     * Walks every key in the flat hash and classifies it:
+     * - **3-char + dimension** (`aBC,0,0`) — activity process state, organized into
+     *   a nested hierarchy by dimension path and symbolized key
+     * - **3-char only** (`aBC`) — top-level job state (done, response, error, etc.)
+     *
+     * The `process` result is a nested tree where dimensions are path segments
+     * (e.g., `{ "0": { "0": { "worker": { "output": { "data": ... } } } } }`).
+     *
+     * @param jobHash - the raw key-value hash from the store
+     * @param dependencyList - raw dependency strings from the store
+     * @returns structured export with process tree, dependencies, and status
      */
     inflate(jobHash: StringStringType, dependencyList: string[]): JobExport;
     /**
@@ -49,11 +83,16 @@ declare class ExporterService {
      */
     buildActivities(process: StringAnyType, streamHistory: StreamHistoryEntry[]): ActivityDetail[];
     /**
-     * Inflates the dependency data into a JobExport object by
-     * organizing the dimensional isolate in such a way as to interleave
-     * into a story
-     * @param data - the dependency data
-     * @returns - the organized dependency data
+     * Parse raw dependency strings into structured {@link DependencyExport} entries.
+     *
+     * Each dependency string encodes the action type, topic, group ID, and job ID
+     * of a spawned sub-job (child workflow, hook, or signal cleanup). The job ID
+     * suffix reveals whether it originated from a hook (dimensional address + counter)
+     * or the main flow (counter only).
+     *
+     * @param data - raw dependency strings from the store
+     * @param actions - accumulator for action tracking (hooks vs main flow)
+     * @returns structured dependency list
      */
     inflateDependencyData(data: string[], actions: JobActionExport): DependencyExport[];
 }

package/build/services/exporter/index.js

@@ -5,8 +5,25 @@ const key_1 = require("../../modules/key");
 const utils_1 = require("../../modules/utils");
 const serializer_1 = require("../serializer");
 /**
- * Downloads job data and expands process data and
- * includes dependency list
+ * System-level exporter for HotMesh job data. Decodes the flat, symbolized
+ * hash stored in Redis/Postgres into a human-readable {@link JobExport}
+ * with three sections:
+ *
+ * - **process** — a nested object reflecting the activity execution tree.
+ *   Each activity's input, output, and metadata are organized by their
+ *   dimensional path (e.g., `0/0/worker/output/data`).
+ * - **dependencies** — list of dependent jobs (child workflows, hooks, signals)
+ *   spawned during execution.
+ * - **status** — the raw semaphore value from the job hash.
+ *
+ * Optionally, set `enrich_inputs: true` to produce a flat `activities` array
+ * ({@link ActivityDetail}[]) that merges stream message history (inputs, timing,
+ * retries) with process outputs — useful for dashboards and debugging views.
+ *
+ * @remarks
+ * This is the lower-level exporter used by the HotMesh engine directly.
+ * For durable workflow exports, use the `ExporterService` in `services/durable/exporter`
+ * which produces structured timeline and execution history formats.
  */
 class ExporterService {
     /** @hidden */
@@ -16,9 +33,18 @@ class ExporterService {
         this.store = store;
     }
     /**
-     * Convert the job hash into a JobExport object.
-     * This object contains various facets that describe the interaction
-     * in terms relevant to narrative storytelling.
+     * Export a job as a structured {@link JobExport}.
+     *
+     * Reads the raw job hash from the store, inflates symbolized keys into
+     * readable paths, and organizes data into `process`, `dependencies`,
+     * and `status` sections.
+     *
+     * When `enrich_inputs` is true, also fetches stream message history and
+     * produces a flat `activities` array with per-activity input/output,
+     * timing, retry attempts, and cycle iteration info.
+     *
+     * @param jobId - the job ID to export
+     * @param options - controls enrichment behavior
      */
     async export(jobId, options = {}) {
         if (!this.symbols) {
@@ -35,18 +61,26 @@ class ExporterService {
         return jobExport;
     }
     /**
-     * Inflates the key
-     * into a human-readable JSON path, reflecting the
-     * tree-like structure of the unidimensional Hash
+     * Resolve a 3-character symbol key to its full path (e.g., `aBC` → `worker/output/data`).
+     * Returns the key unchanged if no symbol mapping exists.
      */
     inflateKey(key) {
         return key in this.symbols ? this.symbols[key] : key;
     }
     /**
-     * Inflates the job data into a JobExport object
-     * @param jobHash - the job data
-     * @param dependencyList - the list of dependencies for the job
-     * @returns - the inflated job data
+     * Decode a raw job hash into a structured {@link JobExport}.
+     *
+     * Walks every key in the flat hash and classifies it:
+     * - **3-char + dimension** (`aBC,0,0`) — activity process state, organized into
+     *   a nested hierarchy by dimension path and symbolized key
+     * - **3-char only** (`aBC`) — top-level job state (done, response, error, etc.)
+     *
+     * The `process` result is a nested tree where dimensions are path segments
+     * (e.g., `{ "0": { "0": { "worker": { "output": { "data": ... } } } } }`).
+     *
+     * @param jobHash - the raw key-value hash from the store
+     * @param dependencyList - raw dependency strings from the store
+     * @returns structured export with process tree, dependencies, and status
      */
     inflate(jobHash, dependencyList) {
         //the list of actions taken in the workflow and hook functions
@@ -154,11 +188,16 @@ class ExporterService {
         return activities;
     }
     /**
-     * Inflates the dependency data into a JobExport object by
-     * organizing the dimensional isolate in such a way as to interleave
-     * into a story
-     * @param data - the dependency data
-     * @returns - the organized dependency data
+     * Parse raw dependency strings into structured {@link DependencyExport} entries.
+     *
+     * Each dependency string encodes the action type, topic, group ID, and job ID
+     * of a spawned sub-job (child workflow, hook, or signal cleanup). The job ID
+     * suffix reveals whether it originated from a hook (dimensional address + counter)
+     * or the main flow (counter only).
+     *
+     * @param data - raw dependency strings from the store
+     * @param actions - accumulator for action tracking (hooks vs main flow)
+     * @returns structured dependency list
      */
     inflateDependencyData(data, actions) {
         const hookReg = /([0-9,]+)-(\d+)$/;

package/build/services/stream/providers/postgres/kvtables.js

@@ -140,21 +140,31 @@ async function createTables(client, schemaName) {
     ) PARTITION BY HASH (stream_name);
   `);
     for (let i = 0; i < 8; i++) {
+        // fillfactor 70: reserves 30% page space for HOT updates (reserve/ack cycle)
         await client.query(`
       CREATE TABLE IF NOT EXISTS ${schemaName}.engine_streams_part_${i}
       PARTITION OF ${engineTable}
-      FOR VALUES WITH (modulus 8, remainder ${i});
+      FOR VALUES WITH (modulus 8, remainder ${i})
+      WITH (fillfactor = 70);
     `);
     }
+    // Dedicated dequeue index: columns match the hot-path query exactly
+    // (stream_name = $1, visible_at <= NOW(), ORDER BY id) with partial
+    // filter on reserved_at IS NULL AND expired_at IS NULL.
+    // Replaces the old active_messages index that had reserved_at as a
+    // column (redundant with the WHERE filter, displacing visible_at).
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_engine_streams_active_messages
-    ON ${engineTable} (stream_name, reserved_at, visible_at, id)
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_dequeue
+    ON ${engineTable} (stream_name, visible_at, id)
     WHERE reserved_at IS NULL AND expired_at IS NULL;
   `);
+    // Stale-reservation recovery: covers the timed-out reservation path
+    // (reserved_at < NOW() - INTERVAL) separately from the hot path so
+    // the planner can use each index cleanly without an OR.
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_engine_streams_message_fetch
-    ON ${engineTable} (stream_name, visible_at, id)
-    WHERE expired_at IS NULL;
+    CREATE INDEX IF NOT EXISTS idx_engine_streams_stale_reservations
+    ON ${engineTable} (stream_name, reserved_at, visible_at, id)
+    WHERE reserved_at IS NOT NULL AND expired_at IS NULL;
   `);
     await client.query(`
     CREATE INDEX IF NOT EXISTS idx_engine_streams_expired_at
@@ -209,21 +219,25 @@ async function createTables(client, schemaName) {
     ) PARTITION BY HASH (stream_name);
   `);
     for (let i = 0; i < 8; i++) {
+        // fillfactor 70: reserves 30% page space for HOT updates (reserve/ack cycle)
         await client.query(`
       CREATE TABLE IF NOT EXISTS ${schemaName}.worker_streams_part_${i}
       PARTITION OF ${workerTable}
-      FOR VALUES WITH (modulus 8, remainder ${i});
+      FOR VALUES WITH (modulus 8, remainder ${i})
+      WITH (fillfactor = 70);
     `);
     }
+    // Dedicated dequeue index (see engine_streams comments above)
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_worker_streams_active_messages
-    ON ${workerTable} (stream_name, reserved_at, visible_at, id)
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_dequeue
+    ON ${workerTable} (stream_name, visible_at, id)
     WHERE reserved_at IS NULL AND expired_at IS NULL;
   `);
+    // Stale-reservation recovery (see engine_streams comments above)
     await client.query(`
-    CREATE INDEX IF NOT EXISTS idx_worker_streams_message_fetch
-    ON ${workerTable} (stream_name, visible_at, id)
-    WHERE expired_at IS NULL;
+    CREATE INDEX IF NOT EXISTS idx_worker_streams_stale_reservations
+    ON ${workerTable} (stream_name, reserved_at, visible_at, id)
+    WHERE reserved_at IS NOT NULL AND expired_at IS NULL;
   `);
     await client.query(`
     CREATE INDEX IF NOT EXISTS idx_worker_streams_expired_at

package/build/services/stream/providers/postgres/messages.js

@@ -207,12 +207,17 @@ async function fetchMessages(client, tableName, streamName, isEngine, consumerNa
             retries++;
             const batchSize = options?.batchSize || 1;
             const reservationTimeout = options?.reservationTimeout || enums_1.HMSH_RESERVATION_TIMEOUT_S;
-            const res = await client.query(`UPDATE ${tableName}
+            // Two-pass dequeue: stale reservations first (FIFO — they have
+            // lower ids and have waited longest), then fresh messages. Split
+            // avoids an OR that prevents the planner from using partial
+            // indexes cleanly. Stale check is a fast no-op (empty index scan)
+            // when there are no timed-out reservations.
+            let res = await client.query(`UPDATE ${tableName}
          SET reserved_at = NOW(), reserved_by = $3
          WHERE id IN (
            SELECT id FROM ${tableName}
            WHERE stream_name = $1
-             AND (reserved_at IS NULL OR reserved_at < NOW() - INTERVAL '${reservationTimeout} seconds')
+             AND reserved_at < NOW() - INTERVAL '${reservationTimeout} seconds'
              AND expired_at IS NULL
              AND visible_at <= NOW()
            ORDER BY id
@@ -220,6 +225,22 @@ async function fetchMessages(client, tableName, streamName, isEngine, consumerNa
            FOR UPDATE SKIP LOCKED
          )
          RETURNING ${returningClause}`, [streamName, batchSize, consumerName]);
+            // Fresh messages: unreserved, visible, not expired
+            if (res.rows.length === 0) {
+                res = await client.query(`UPDATE ${tableName}
+           SET reserved_at = NOW(), reserved_by = $3
+           WHERE id IN (
+             SELECT id FROM ${tableName}
+             WHERE stream_name = $1
+               AND reserved_at IS NULL
+               AND expired_at IS NULL
+               AND visible_at <= NOW()
+             ORDER BY id
+             LIMIT $2
+             FOR UPDATE SKIP LOCKED
+           )
+           RETURNING ${returningClause}`, [streamName, batchSize, consumerName]);
+            }
             const messages = res.rows.map((row) => {
                 const data = (0, utils_1.parseStreamMessage)(row.message);
                 const hasDefaultRetryPolicy = (row.max_retry_attempts === 3 || row.max_retry_attempts === 5) &&

package/build/services/stream/providers/postgres/procedures.js

@@ -54,13 +54,16 @@ function getCreateProceduresSQL(schemaName) {
     SET search_path = ${schemaName}, pg_temp
     AS $$
     ${STREAM_ACCESS_CHECK}
+      -- Two-pass dequeue: stale reservations first (FIFO — lower ids,
+      -- waited longest), then fresh. Split avoids OR that prevents
+      -- partial index usage. Stale check is a fast no-op when empty.
       RETURN QUERY
       UPDATE ${workerTable} ws
       SET reserved_at = NOW(), reserved_by = p_consumer_id
       WHERE ws.id IN (
         SELECT ws2.id FROM ${workerTable} ws2
         WHERE ws2.stream_name = p_stream_name
-          AND (ws2.reserved_at IS NULL OR ws2.reserved_at < NOW() - (p_reservation_timeout_sec || ' seconds')::INTERVAL)
+          AND ws2.reserved_at < NOW() - (p_reservation_timeout_sec || ' seconds')::INTERVAL
           AND ws2.expired_at IS NULL
           AND ws2.visible_at <= NOW()
         ORDER BY ws2.id
@@ -69,6 +72,25 @@ function getCreateProceduresSQL(schemaName) {
       )
       RETURNING ws.id, ws.message, ws.workflow_name, ws.max_retry_attempts,
                 ws.backoff_coefficient, ws.maximum_interval_seconds, ws.retry_attempt;
+
+      -- Fresh messages: unreserved, visible, not expired
+      IF NOT FOUND THEN
+        RETURN QUERY
+        UPDATE ${workerTable} ws
+        SET reserved_at = NOW(), reserved_by = p_consumer_id
+        WHERE ws.id IN (
+          SELECT ws2.id FROM ${workerTable} ws2
+          WHERE ws2.stream_name = p_stream_name
+            AND ws2.reserved_at IS NULL
+            AND ws2.expired_at IS NULL
+            AND ws2.visible_at <= NOW()
+          ORDER BY ws2.id
+          LIMIT p_batch_size
+          FOR UPDATE SKIP LOCKED
+        )
+        RETURNING ws.id, ws.message, ws.workflow_name, ws.max_retry_attempts,
+                  ws.backoff_coefficient, ws.maximum_interval_seconds, ws.retry_attempt;
+      END IF;
     END;
     $$;`,
         // -- worker_ack --

package/build/types/exporter.d.ts

@@ -1,7 +1,14 @@
 import { StringAnyType } from './serializer';
 export type ExportItem = [string | null, string, any];
 /**
- * job export data can be large, particularly transitions the timeline
+ * Selectable sections of a {@link DurableJobExport}. Use with `allow` (allowlist)
+ * or `block` (blocklist) in {@link ExportOptions} to control export size.
+ *
+ * - `data` — workflow input arguments
+ * - `state` — current state (done, response, error, timestamps)
+ * - `status` — semaphore value
+ * - `timeline` — idempotent operation markers (can be large for complex workflows)
+ * - `transitions` — activity execution timestamps (can be large with many cycles)
  */
 export type ExportFields = 'data' | 'state' | 'status' | 'timeline' | 'transitions';
 export interface ExportOptions {
@@ -74,6 +81,19 @@ export interface TransitionType {
     created: string;
     updated: string;
 }
+/**
+ * Raw export of a durable workflow job, returned by `handle.export()`.
+ *
+ * Contains five sections (filterable via {@link ExportOptions}):
+ *
+ * | Section | Type | Description |
+ * |---|---|---|
+ * | `data` | object | Workflow input arguments passed to `workflow.start()` |
+ * | `state` | object | Current state: `done` flag, `response`, `$error`, `jc`/`ju` timestamps |
+ * | `status` | number | Semaphore: `0` = idle/complete, `> 0` = pending activities, `< 0` = error |
+ * | `timeline` | array | Ordered idempotent markers for each operation (proxy, child, sleep, signal) |
+ * | `transitions` | array | Activity start/stop timestamps organized by dimension |
+ */
 export interface DurableJobExport {
     data?: StringAnyType;
     state?: StringAnyType;
@@ -212,6 +232,20 @@ export interface WorkflowExecutionSummary {
     signals: number;
 }
 export type WorkflowExecutionStatus = 'running' | 'completed' | 'failed';
+/**
+ * Structured execution history for a durable workflow, returned by
+ * `handle.exportExecution()`.
+ *
+ * Events are chronologically ordered with sequential `event_id` values.
+ * Completed/failed events carry `scheduled_event_id` or `initiated_event_id`
+ * back-references to their corresponding scheduled/started events.
+ *
+ * The `summary` provides aggregate counts by category (activities, child
+ * workflows, timers, signals) for quick dashboard rendering.
+ *
+ * In `verbose` mode, `children` contains recursively fetched child workflow
+ * executions, each with their own events and summaries.
+ */
 export interface WorkflowExecution {
     workflow_id: string;
     workflow_type: string;
@@ -226,10 +260,33 @@ export interface WorkflowExecution {
     children?: WorkflowExecution[];
     stream_history?: StreamHistoryEntry[];
 }
+/**
+ * Options for `handle.exportExecution()`. Controls event filtering, enrichment,
+ * and traversal depth for child workflows.
+ */
 export interface ExecutionExportOptions {
+    /**
+     * `sparse` (default) — single-query export from the workflow's timeline markers.
+     * `verbose` — recursively fetches child workflow jobs and attaches their full
+     * event histories as nested `children` arrays.
+     */
     mode?: ExportMode;
+    /**
+     * When true, omits internal/interceptor activities (names starting with `lt`)
+     * from the event list. Useful for user-facing dashboards.
+     * @default false
+     */
     exclude_system?: boolean;
+    /**
+     * When true, strips `result` and `input` payloads from event attributes.
+     * Reduces response size while preserving event structure and timing.
+     * @default false
+     */
     omit_results?: boolean;
+    /**
+     * Maximum recursion depth for verbose mode child workflow fetching.
+     * @default 5
+     */
     max_depth?: number;
     /**
      * When true, enriches activity and child workflow events with their inputs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.14.9",
+  "version": "0.15.1",
   "description": "Durable Workflow",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",