@hotmeshio/hotmesh 0.10.0 → 0.10.2

package/README.md

@@ -11,7 +11,7 @@ npm install @hotmeshio/hotmesh
 ## Use HotMesh for
 
 - **Durable pipelines** — Orchestrate long-running, multi-step pipelines transactionally.
-- **Temporal replacement** — The `Durable` module provides a Temporal-compatible API (`Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`, signals) that runs directly on Postgres. No app server required.
+- **Temporal alternative** — The `Durable` module provides a Temporal-compatible API (`Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`, signals) that runs directly on Postgres. No app server required.
 - **Distributed state machines** — Build stateful applications where every component can [fail and recover](https://github.com/hotmeshio/sdk-typescript/blob/main/services/collator/README.md).
 - **AI and training pipelines** — Multi-step AI workloads where each stage is expensive and must not be repeated on failure. A crashed pipeline resumes from the last committed step, not from the beginning.
 
@@ -337,7 +337,7 @@ Durable is designed as a drop-in-compatible alternative for common Temporal patt
 
 **What's the same:** `Client`, `Worker`, `proxyActivities`, `sleepFor`, `startChild`/`execChild`, signals (`waitFor`/`signal`), retry policies, and the overall workflow-as-code programming model.
 
-**What's different:** No Temporal server or cluster to operate. Postgres is the only infrastructure dependency — it stores state, coordinates workers, and delivers messages. HotMesh also offers a YAML-based approach for declarative workflows that compile to the same execution model.
+**What's different:** Postgres is the only infrastructure dependency — it stores state and coordinates workers.
 
 ## Running tests
 

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.10.0",
+    "version": "0.10.2",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -46,6 +46,8 @@
         "test:durable:sleep": "vitest run tests/durable/sleep/postgres.test.ts",
         "test:durable:signal": "vitest run tests/durable/signal/postgres.test.ts",
         "test:durable:unknown": "vitest run tests/durable/unknown/postgres.test.ts",
+        "test:durable:exporter": "vitest run tests/durable/exporter/exporter.test.ts",
+        "test:durable:exporter:debug": "EXPORT_DEBUG=1 HMSH_LOGLEVEL=error vitest run tests/durable/basic/postgres.test.ts",
         "test:dba": "vitest run tests/dba",
         "test:cycle": "vitest run tests/functional/cycle",
         "test:functional": "vitest run tests/functional",
@@ -110,13 +112,12 @@
         "nats": "^2.28.0",
         "openai": "^5.9.0",
         "pg": "^8.10.0",
-        "rimraf": "^4.4.1",
+        "rimraf": "^6.1.3",
         "terser": "^5.37.0",
         "ts-node": "^10.9.1",
-        "ts-node-dev": "^2.0.0",
         "typedoc": "^0.26.4",
         "typescript": "^5.0.4",
-        "vitest": "^2.1.9"
+        "vitest": "^4.0.18"
     },
     "peerDependencies": {
         "nats": "^2.0.0",

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

@@ -11,7 +11,7 @@ import { PostgresClientType } from '../../types/postgres';
  * | Table | What accumulates |
  * |---|---|
  * | `{appId}.jobs` | Completed/expired jobs with `expired_at` set |
- * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `jmark`, `status`, `other`) that are only needed during workflow execution |
+ * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.streams` | Processed stream messages with `expired_at` set |
  *
  * The `DBA` service addresses this with two methods:
@@ -22,10 +22,29 @@ import { PostgresClientType } from '../../types/postgres';
  * - {@link DBA.deploy | deploy()} — Pre-deploys the Postgres function
  *   (e.g., during CI/CD migrations) without running a prune.
  *
- * ## Independent cron schedules (TypeScript)
+ * ## Attribute stripping preserves export history
+ *
+ * Stripping removes `adata`, `hmark`, `status`, and `other` attributes
+ * from completed jobs while preserving:
+ * - `jdata` — workflow return data
+ * - `udata` — user-searchable data
+ * - `jmark` — timeline markers needed for Temporal-compatible export
+ *
+ * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
+ *
+ * ## Entity-scoped pruning
  *
- * Each table can be targeted independently, allowing different retention
- * windows and schedules:
+ * Use `entities` to restrict pruning/stripping to specific entity types
+ * (e.g., `['book', 'author']`). Use `pruneTransient` to delete expired
+ * jobs with no entity (`entity IS NULL`).
+ *
+ * ## Idempotent stripping with `pruned_at`
+ *
+ * After stripping, jobs are marked with `pruned_at = NOW()`. Subsequent
+ * prune calls skip already-pruned jobs, making the operation idempotent
+ * and efficient for repeated scheduling.
+ *
+ * ## Independent cron schedules (TypeScript)
  *
  * @example
  * ```typescript
@@ -38,7 +57,6 @@ import { PostgresClientType } from '../../types/postgres';
  * };
  *
  * // Cron 1 — Nightly: strip execution artifacts from completed jobs
- * //          Keeps all jobs and their jdata/udata; keeps all streams.
  * await DBA.prune({
  *   appId: 'myapp', connection,
  *   jobs: false, streams: false, attributes: true,
@@ -51,29 +69,34 @@ import { PostgresClientType } from '../../types/postgres';
  *   jobs: false, streams: true,
  * });
  *
- * // Cron 3 — Weekly: remove expired jobs older than 30 days
+ * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
  * await DBA.prune({
  *   appId: 'myapp', connection,
  *   expire: '30 days',
  *   jobs: true, streams: false,
+ *   entities: ['book'],
+ * });
+ *
+ * // Cron 4 — Weekly: remove transient (no entity) expired jobs
+ * await DBA.prune({
+ *   appId: 'myapp', connection,
+ *   expire: '7 days',
+ *   jobs: false, streams: false,
+ *   pruneTransient: true,
  * });
  * ```
  *
  * ## Direct SQL (schedulable via pg_cron)
  *
  * The underlying Postgres function can be called directly, without
- * the TypeScript SDK. Schedule it via `pg_cron`, `crontab`, or any
- * SQL client:
+ * the TypeScript SDK. The first 4 parameters are backwards-compatible:
  *
  * ```sql
  * -- Strip attributes only (keep all jobs and streams)
  * SELECT * FROM myapp.prune('0 seconds', false, false, true);
  *
- * -- Prune streams older than 24 hours (keep jobs)
- * SELECT * FROM myapp.prune('24 hours', false, true, false);
- *
- * -- Prune expired jobs older than 30 days (keep streams)
- * SELECT * FROM myapp.prune('30 days', true, false, false);
+ * -- Prune only 'book' entity jobs older than 30 days
+ * SELECT * FROM myapp.prune('30 days', true, false, false, ARRAY['book']);
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
@@ -98,6 +121,12 @@ declare class DBA {
         client: PostgresClientType;
         release: () => Promise<void>;
     }>;
+    /**
+     * Returns migration SQL for the `pruned_at` column.
+     * Handles existing deployments that lack the column.
+     * @private
+     */
+    static getMigrationSQL(schema: string): string;
     /**
      * Returns the SQL for the server-side `prune()` function.
      * @private
@@ -105,7 +134,8 @@ declare class DBA {
     static getPruneFunctionSQL(schema: string): string;
     /**
      * Deploys the `prune()` Postgres function into the target schema.
-     * Idempotent — uses `CREATE OR REPLACE` and can be called repeatedly.
+     * Also runs schema migrations (e.g., adding `pruned_at` column).
+     * Idempotent — uses `CREATE OR REPLACE` and `IF NOT EXISTS`.
      *
      * The function is automatically deployed when {@link DBA.prune} is called,
      * but this method is exposed for explicit control (e.g., CI/CD
@@ -138,12 +168,15 @@ declare class DBA {
      *
      * Operations (each enabled individually):
      * 1. **jobs** — Hard-deletes expired jobs older than the retention
-     *    window (FK CASCADE removes their attributes automatically)
+     *    window (FK CASCADE removes their attributes automatically).
+     *    Scoped by `entities` when set.
      * 2. **streams** — Hard-deletes expired stream messages older than
      *    the retention window
      * 3. **attributes** — Strips non-essential attributes (`adata`,
-     *    `hmark`, `jmark`, `status`, `other`) from completed jobs,
-     *    retaining only `jdata` and `udata`
+     *    `hmark`, `status`, `other`) from completed, un-pruned jobs.
+     *    Preserves `jdata`, `udata`, and `jmark`. Marks stripped
+     *    jobs with `pruned_at` for idempotency.
+     * 4. **pruneTransient** — Deletes expired jobs with `entity IS NULL`
      *
      * @param options - Prune configuration
      * @returns Counts of deleted/stripped rows
@@ -153,7 +186,7 @@ declare class DBA {
      * import { Client as Postgres } from 'pg';
      * import { DBA } from '@hotmeshio/hotmesh';
      *
-     * // Strip attributes only — keep all jobs and streams
+     * // Strip attributes from 'book' entities only
      * await DBA.prune({
      *   appId: 'myapp',
      *   connection: {
@@ -163,6 +196,7 @@ declare class DBA {
      *   jobs: false,
      *   streams: false,
      *   attributes: true,
+     *   entities: ['book'],
      * });
      * ```
      */

package/build/services/dba/index.js

@@ -14,7 +14,7 @@ const postgres_1 = require("../connector/providers/postgres");
  * | Table | What accumulates |
  * |---|---|
  * | `{appId}.jobs` | Completed/expired jobs with `expired_at` set |
- * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `jmark`, `status`, `other`) that are only needed during workflow execution |
+ * | `{appId}.jobs_attributes` | Execution artifacts (`adata`, `hmark`, `status`, `other`) that are only needed during workflow execution |
  * | `{appId}.streams` | Processed stream messages with `expired_at` set |
  *
  * The `DBA` service addresses this with two methods:
@@ -25,10 +25,29 @@ const postgres_1 = require("../connector/providers/postgres");
  * - {@link DBA.deploy | deploy()} — Pre-deploys the Postgres function
  *   (e.g., during CI/CD migrations) without running a prune.
  *
- * ## Independent cron schedules (TypeScript)
+ * ## Attribute stripping preserves export history
+ *
+ * Stripping removes `adata`, `hmark`, `status`, and `other` attributes
+ * from completed jobs while preserving:
+ * - `jdata` — workflow return data
+ * - `udata` — user-searchable data
+ * - `jmark` — timeline markers needed for Temporal-compatible export
+ *
+ * Set `keepHmark: true` to also preserve `hmark` (activity state markers).
+ *
+ * ## Entity-scoped pruning
  *
- * Each table can be targeted independently, allowing different retention
- * windows and schedules:
+ * Use `entities` to restrict pruning/stripping to specific entity types
+ * (e.g., `['book', 'author']`). Use `pruneTransient` to delete expired
+ * jobs with no entity (`entity IS NULL`).
+ *
+ * ## Idempotent stripping with `pruned_at`
+ *
+ * After stripping, jobs are marked with `pruned_at = NOW()`. Subsequent
+ * prune calls skip already-pruned jobs, making the operation idempotent
+ * and efficient for repeated scheduling.
+ *
+ * ## Independent cron schedules (TypeScript)
  *
  * @example
  * ```typescript
@@ -41,7 +60,6 @@ const postgres_1 = require("../connector/providers/postgres");
  * };
  *
  * // Cron 1 — Nightly: strip execution artifacts from completed jobs
- * //          Keeps all jobs and their jdata/udata; keeps all streams.
  * await DBA.prune({
  *   appId: 'myapp', connection,
  *   jobs: false, streams: false, attributes: true,
@@ -54,29 +72,34 @@ const postgres_1 = require("../connector/providers/postgres");
  *   jobs: false, streams: true,
  * });
  *
- * // Cron 3 — Weekly: remove expired jobs older than 30 days
+ * // Cron 3 — Weekly: remove expired 'book' jobs older than 30 days
  * await DBA.prune({
  *   appId: 'myapp', connection,
  *   expire: '30 days',
  *   jobs: true, streams: false,
+ *   entities: ['book'],
+ * });
+ *
+ * // Cron 4 — Weekly: remove transient (no entity) expired jobs
+ * await DBA.prune({
+ *   appId: 'myapp', connection,
+ *   expire: '7 days',
+ *   jobs: false, streams: false,
+ *   pruneTransient: true,
  * });
  * ```
  *
  * ## Direct SQL (schedulable via pg_cron)
  *
  * The underlying Postgres function can be called directly, without
- * the TypeScript SDK. Schedule it via `pg_cron`, `crontab`, or any
- * SQL client:
+ * the TypeScript SDK. The first 4 parameters are backwards-compatible:
  *
  * ```sql
  * -- Strip attributes only (keep all jobs and streams)
  * SELECT * FROM myapp.prune('0 seconds', false, false, true);
  *
- * -- Prune streams older than 24 hours (keep jobs)
- * SELECT * FROM myapp.prune('24 hours', false, true, false);
- *
- * -- Prune expired jobs older than 30 days (keep streams)
- * SELECT * FROM myapp.prune('30 days', true, false, false);
+ * -- Prune only 'book' entity jobs older than 30 days
+ * SELECT * FROM myapp.prune('30 days', true, false, false, ARRAY['book']);
  *
  * -- Prune everything older than 7 days and strip attributes
  * SELECT * FROM myapp.prune('7 days', true, true, true);
@@ -121,6 +144,20 @@ class DBA {
             release: async () => { },
         };
     }
+    /**
+     * Returns migration SQL for the `pruned_at` column.
+     * Handles existing deployments that lack the column.
+     * @private
+     */
+    static getMigrationSQL(schema) {
+        return `
+      ALTER TABLE ${schema}.jobs
+      ADD COLUMN IF NOT EXISTS pruned_at TIMESTAMP WITH TIME ZONE;
+
+      CREATE INDEX IF NOT EXISTS idx_jobs_pruned_at
+      ON ${schema}.jobs (pruned_at) WHERE pruned_at IS NULL;
+    `;
+    }
     /**
      * Returns the SQL for the server-side `prune()` function.
      * @private
@@ -131,12 +168,17 @@ class DBA {
         retention INTERVAL DEFAULT INTERVAL '7 days',
         prune_jobs BOOLEAN DEFAULT TRUE,
         prune_streams BOOLEAN DEFAULT TRUE,
-        strip_attributes BOOLEAN DEFAULT FALSE
+        strip_attributes BOOLEAN DEFAULT FALSE,
+        entity_list TEXT[] DEFAULT NULL,
+        prune_transient BOOLEAN DEFAULT FALSE,
+        keep_hmark BOOLEAN DEFAULT FALSE
       )
       RETURNS TABLE(
         deleted_jobs BIGINT,
         deleted_streams BIGINT,
-        stripped_attributes BIGINT
+        stripped_attributes BIGINT,
+        deleted_transient BIGINT,
+        marked_pruned BIGINT
       )
       LANGUAGE plpgsql
       AS $$
@@ -144,17 +186,30 @@ class DBA {
         v_deleted_jobs BIGINT := 0;
         v_deleted_streams BIGINT := 0;
         v_stripped_attributes BIGINT := 0;
+        v_deleted_transient BIGINT := 0;
+        v_marked_pruned BIGINT := 0;
       BEGIN
         -- 1. Hard-delete expired jobs older than the retention window.
         --    FK CASCADE on jobs_attributes handles attribute cleanup.
+        --    Optionally scoped to an entity allowlist.
         IF prune_jobs THEN
           DELETE FROM ${schema}.jobs
           WHERE expired_at IS NOT NULL
-            AND expired_at < NOW() - retention;
+            AND expired_at < NOW() - retention
+            AND (entity_list IS NULL OR entity = ANY(entity_list));
           GET DIAGNOSTICS v_deleted_jobs = ROW_COUNT;
         END IF;
 
-        -- 2. Hard-delete expired stream messages older than the retention window.
+        -- 2. Hard-delete transient (entity IS NULL) expired jobs.
+        IF prune_transient THEN
+          DELETE FROM ${schema}.jobs
+          WHERE entity IS NULL
+            AND expired_at IS NOT NULL
+            AND expired_at < NOW() - retention;
+          GET DIAGNOSTICS v_deleted_transient = ROW_COUNT;
+        END IF;
+
+        -- 3. Hard-delete expired stream messages older than the retention window.
         IF prune_streams THEN
           DELETE FROM ${schema}.streams
           WHERE expired_at IS NOT NULL
@@ -162,22 +217,45 @@ class DBA {
           GET DIAGNOSTICS v_deleted_streams = ROW_COUNT;
         END IF;
 
-        -- 3. Optionally strip execution artifacts from completed, live jobs.
-        --    Retains jdata (workflow return data) and udata (searchable data).
+        -- 4. Strip execution artifacts from completed, live, un-pruned jobs.
+        --    Always preserves: jdata, udata, jmark (timeline/export history).
+        --    Optionally preserves: hmark (when keep_hmark is true).
         IF strip_attributes THEN
-          DELETE FROM ${schema}.jobs_attributes
-          WHERE job_id IN (
+          WITH target_jobs AS (
+            SELECT id FROM ${schema}.jobs
+            WHERE status = 0
+              AND is_live = TRUE
+              AND pruned_at IS NULL
+              AND (entity_list IS NULL OR entity = ANY(entity_list))
+          ),
+          deleted AS (
+            DELETE FROM ${schema}.jobs_attributes
+            WHERE job_id IN (SELECT id FROM target_jobs)
+              AND type NOT IN ('jdata', 'udata', 'jmark')
+              AND (keep_hmark = FALSE OR type <> 'hmark')
+            RETURNING job_id
+          )
+          SELECT COUNT(*) INTO v_stripped_attributes FROM deleted;
+
+          -- Mark pruned jobs so they are skipped on future runs.
+          WITH target_jobs AS (
             SELECT id FROM ${schema}.jobs
             WHERE status = 0
               AND is_live = TRUE
+              AND pruned_at IS NULL
+              AND (entity_list IS NULL OR entity = ANY(entity_list))
           )
-          AND type NOT IN ('jdata', 'udata');
-          GET DIAGNOSTICS v_stripped_attributes = ROW_COUNT;
+          UPDATE ${schema}.jobs
+          SET pruned_at = NOW()
+          WHERE id IN (SELECT id FROM target_jobs);
+          GET DIAGNOSTICS v_marked_pruned = ROW_COUNT;
         END IF;
 
         deleted_jobs := v_deleted_jobs;
         deleted_streams := v_deleted_streams;
         stripped_attributes := v_stripped_attributes;
+        deleted_transient := v_deleted_transient;
+        marked_pruned := v_marked_pruned;
         RETURN NEXT;
       END;
       $$;
@@ -185,7 +263,8 @@ class DBA {
     }
     /**
      * Deploys the `prune()` Postgres function into the target schema.
-     * Idempotent — uses `CREATE OR REPLACE` and can be called repeatedly.
+     * Also runs schema migrations (e.g., adding `pruned_at` column).
+     * Idempotent — uses `CREATE OR REPLACE` and `IF NOT EXISTS`.
      *
      * The function is automatically deployed when {@link DBA.prune} is called,
      * but this method is exposed for explicit control (e.g., CI/CD
@@ -214,6 +293,7 @@ class DBA {
         const schema = DBA.safeName(appId);
         const { client, release } = await DBA.getClient(connection);
         try {
+            await client.query(DBA.getMigrationSQL(schema));
             await client.query(DBA.getPruneFunctionSQL(schema));
         }
         finally {
@@ -227,12 +307,15 @@ class DBA {
      *
      * Operations (each enabled individually):
      * 1. **jobs** — Hard-deletes expired jobs older than the retention
-     *    window (FK CASCADE removes their attributes automatically)
+     *    window (FK CASCADE removes their attributes automatically).
+     *    Scoped by `entities` when set.
      * 2. **streams** — Hard-deletes expired stream messages older than
      *    the retention window
      * 3. **attributes** — Strips non-essential attributes (`adata`,
-     *    `hmark`, `jmark`, `status`, `other`) from completed jobs,
-     *    retaining only `jdata` and `udata`
+     *    `hmark`, `status`, `other`) from completed, un-pruned jobs.
+     *    Preserves `jdata`, `udata`, and `jmark`. Marks stripped
+     *    jobs with `pruned_at` for idempotency.
+     * 4. **pruneTransient** — Deletes expired jobs with `entity IS NULL`
      *
      * @param options - Prune configuration
      * @returns Counts of deleted/stripped rows
@@ -242,7 +325,7 @@ class DBA {
      * import { Client as Postgres } from 'pg';
      * import { DBA } from '@hotmeshio/hotmesh';
      *
-     * // Strip attributes only — keep all jobs and streams
+     * // Strip attributes from 'book' entities only
      * await DBA.prune({
      *   appId: 'myapp',
      *   connection: {
@@ -252,6 +335,7 @@ class DBA {
      *   jobs: false,
      *   streams: false,
      *   attributes: true,
+     *   entities: ['book'],
      * });
      * ```
      */
@@ -261,15 +345,20 @@ class DBA {
         const jobs = options.jobs ?? true;
         const streams = options.streams ?? true;
         const attributes = options.attributes ?? false;
+        const entities = options.entities ?? null;
+        const pruneTransient = options.pruneTransient ?? false;
+        const keepHmark = options.keepHmark ?? false;
         await DBA.deploy(options.connection, options.appId);
         const { client, release } = await DBA.getClient(options.connection);
         try {
-            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean)`, [expire, jobs, streams, attributes]);
+            const result = await client.query(`SELECT * FROM ${schema}.prune($1::interval, $2::boolean, $3::boolean, $4::boolean, $5::text[], $6::boolean, $7::boolean)`, [expire, jobs, streams, attributes, entities, pruneTransient, keepHmark]);
             const row = result.rows[0];
             return {
                 jobs: Number(row.deleted_jobs),
                 streams: Number(row.deleted_streams),
                 attributes: Number(row.stripped_attributes),
+                transient: Number(row.deleted_transient),
+                marked: Number(row.marked_pruned),
             };
         }
         finally {

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

@@ -1,8 +1,46 @@
 import { ILogger } from '../logger';
 import { StoreService } from '../store';
-import { ExportOptions, DurableJobExport, TimelineType, TransitionType, ExportFields } from '../../types/exporter';
+import { ExportOptions, DurableJobExport, TimelineType, TransitionType, ExportFields, ExecutionExportOptions, WorkflowExecution, WorkflowExecutionStatus } from '../../types/exporter';
 import { ProviderClient, ProviderTransaction } from '../../types/provider';
 import { StringStringType, Symbols } from '../../types/serializer';
+/**
+ * Parse a HotMesh compact timestamp (YYYYMMDDHHmmss.mmm) into ISO 8601.
+ * Also accepts ISO 8601 strings directly.
+ */
+declare function parseTimestamp(raw: string | undefined | null): string | null;
+/**
+ * Compute duration in milliseconds between two HotMesh timestamps.
+ */
+declare function computeDuration(ac: string | undefined, au: string | undefined): number | null;
+/**
+ * Extract the operation type (proxy, child, start, wait, sleep, hook)
+ * from a timeline key like `-proxy,0,0-1-`.
+ */
+declare function extractOperation(key: string): string;
+/**
+ * Extract the activity name from a timeline entry value's job_id.
+ *
+ * Job ID format: `-{workflowId}-$${activityName}{dimension}-{execIndex}`
+ * Examples:
+ *   `-wfId-$analyzeContent-5`  → `'analyzeContent'`
+ *   `-wfId-$processOrder,0,0-3` → `'processOrder'`
+ */
+declare function extractActivityName(value: Record<string, any> | null): string;
+/**
+ * Check if an activity name is a system (interceptor) operation.
+ */
+declare function isSystemActivity(name: string): boolean;
+/**
+ * Map HotMesh job state to a human-readable execution status.
+ *
+ * HotMesh semaphore: `0` = idle, `> 0` = pending activities,
+ * `< 0` = failed / interrupted.
+ *
+ * A workflow can be "done" (`state.data.done === true`) while the
+ * semaphore is still > 0 (cleanup activities pending). We check
+ * both the `done` flag and the semaphore to determine status.
+ */
+declare function mapStatus(rawStatus: number | undefined, isDone?: boolean, hasError?: boolean): WorkflowExecutionStatus;
 declare class ExporterService {
     appId: string;
     logger: ILogger;
@@ -11,10 +49,29 @@ declare class ExporterService {
     private static symbols;
     constructor(appId: string, store: StoreService<ProviderClient, ProviderTransaction>, logger: ILogger);
     /**
-     * Convert the job hash from its compiles format into a DurableJobExport object with
+     * 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(jobId: string, options?: ExportOptions): Promise<DurableJobExport>;
+    /**
+     * Export a workflow execution as a Temporal-compatible event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list. No additional I/O beyond the initial export.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their executions as nested `children`.
+     */
+    exportExecution(jobId: string, workflowTopic: string, options?: ExecutionExportOptions): Promise<WorkflowExecution>;
+    /**
+     * Pure transformation: convert a raw DurableJobExport into a
+     * Temporal-compatible WorkflowExecution event history.
+     */
+    transformToExecution(raw: DurableJobExport, workflowId: string, workflowTopic: string, options: ExecutionExportOptions): WorkflowExecution;
+    /**
+     * Recursively fetch child workflow executions for verbose mode.
+     */
+    private fetchChildren;
     /**
      * Inflates the job data into a DurableJobExport object
      * @param jobHash - the job data
@@ -48,4 +105,4 @@ declare class ExporterService {
      */
     sortParts(parts: TimelineType[]): TimelineType[];
 }
-export { ExporterService };
+export { ExporterService, parseTimestamp, computeDuration, extractOperation, extractActivityName, isSystemActivity, mapStatus, };