@hotmeshio/hotmesh 0.10.1 → 0.10.2

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.10.1",
+    "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",

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, };

package/build/services/durable/exporter.js

@@ -1,8 +1,158 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExporterService = void 0;
+exports.mapStatus = exports.isSystemActivity = exports.extractActivityName = exports.extractOperation = exports.computeDuration = exports.parseTimestamp = exports.ExporterService = void 0;
 const utils_1 = require("../../modules/utils");
 const serializer_1 = require("../serializer");
+// ── Timestamp helpers ────────────────────────────────────────────────────────
+/**
+ * Parse a HotMesh compact timestamp (YYYYMMDDHHmmss.mmm) into ISO 8601.
+ * Also accepts ISO 8601 strings directly.
+ */
+function parseTimestamp(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const m = raw.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:\.?(\d+))?$/);
+    if (m) {
+        const [, yr, mo, dy, hr, mi, sc, ms] = m;
+        const frac = ms ? `.${ms.padEnd(3, '0').slice(0, 3)}` : '.000';
+        return `${yr}-${mo}-${dy}T${hr}:${mi}:${sc}${frac}Z`;
+    }
+    // Try ISO 8601
+    if (raw.includes('T') || raw.includes('-')) {
+        const d = new Date(raw);
+        if (!isNaN(d.getTime()))
+            return d.toISOString();
+    }
+    return null;
+}
+exports.parseTimestamp = parseTimestamp;
+/**
+ * Compute duration in milliseconds between two HotMesh timestamps.
+ */
+function computeDuration(ac, au) {
+    const start = parseTimestamp(ac);
+    const end = parseTimestamp(au);
+    if (!start || !end)
+        return null;
+    return new Date(end).getTime() - new Date(start).getTime();
+}
+exports.computeDuration = computeDuration;
+// ── Timeline key parsing ─────────────────────────────────────────────────────
+/**
+ * Extract the operation type (proxy, child, start, wait, sleep, hook)
+ * from a timeline key like `-proxy,0,0-1-`.
+ */
+function extractOperation(key) {
+    const parts = key.split('-').filter(Boolean);
+    return parts[0]?.split(',')[0] || 'unknown';
+}
+exports.extractOperation = extractOperation;
+// ── Name extraction ──────────────────────────────────────────────────────────
+/**
+ * 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'`
+ */
+function extractActivityName(value) {
+    const jobId = value?.job_id;
+    if (!jobId || typeof jobId !== 'string')
+        return 'unknown';
+    const dollarIdx = jobId.lastIndexOf('$');
+    if (dollarIdx === -1)
+        return jobId;
+    const afterDollar = jobId.substring(dollarIdx + 1);
+    const dashIdx = afterDollar.lastIndexOf('-');
+    const nameWithDim = dashIdx > 0 ? afterDollar.substring(0, dashIdx) : afterDollar;
+    // Strip dimension suffix (,N,N...)
+    const commaIdx = nameWithDim.indexOf(',');
+    return (commaIdx > 0 ? nameWithDim.substring(0, commaIdx) : nameWithDim) || 'unknown';
+}
+exports.extractActivityName = extractActivityName;
+/**
+ * Check if an activity name is a system (interceptor) operation.
+ */
+function isSystemActivity(name) {
+    return name.startsWith('lt');
+}
+exports.isSystemActivity = isSystemActivity;
+/**
+ * Extract a child workflow ID from a child/start timeline value.
+ */
+function extractChildWorkflowId(value) {
+    return value?.job_id || 'unknown';
+}
+// ── Status mapping ───────────────────────────────────────────────────────────
+/**
+ * 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.
+ */
+function mapStatus(rawStatus, isDone, hasError) {
+    if (hasError || (rawStatus !== undefined && !isNaN(rawStatus) && rawStatus < 0)) {
+        return 'failed';
+    }
+    if (isDone || rawStatus === 0)
+        return 'completed';
+    if (rawStatus === undefined || isNaN(rawStatus))
+        return 'running';
+    return 'running';
+}
+exports.mapStatus = mapStatus;
+// ── Event construction ───────────────────────────────────────────────────────
+function makeEvent(event_id, event_type, category, event_time, duration_ms, is_system, attributes) {
+    return { event_id, event_type, category, event_time, duration_ms, is_system, attributes };
+}
+function computeSummary(events) {
+    const summary = {
+        total_events: events.length,
+        activities: { total: 0, completed: 0, failed: 0, system: 0, user: 0 },
+        child_workflows: { total: 0, completed: 0, failed: 0 },
+        timers: 0,
+        signals: 0,
+    };
+    for (const e of events) {
+        switch (e.event_type) {
+            case 'activity_task_scheduled':
+                summary.activities.total++;
+                if (e.is_system)
+                    summary.activities.system++;
+                else
+                    summary.activities.user++;
+                break;
+            case 'activity_task_completed':
+                summary.activities.completed++;
+                break;
+            case 'activity_task_failed':
+                summary.activities.failed++;
+                break;
+            case 'child_workflow_execution_started':
+                summary.child_workflows.total++;
+                break;
+            case 'child_workflow_execution_completed':
+                summary.child_workflows.completed++;
+                break;
+            case 'child_workflow_execution_failed':
+                summary.child_workflows.failed++;
+                break;
+            case 'timer_started':
+                summary.timers++;
+                break;
+            case 'workflow_execution_signaled':
+                summary.signals++;
+                break;
+        }
+    }
+    return summary;
+}
+// ── Exporter Service ─────────────────────────────────────────────────────────
 class ExporterService {
     constructor(appId, store, logger) {
         this.appId = appId;
@@ -10,7 +160,7 @@ class ExporterService {
         this.store = store;
     }
     /**
-     * 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.
      */
     async export(jobId, options = {}) {
@@ -22,6 +172,284 @@ class ExporterService {
         const jobExport = this.inflate(jobData, options);
         return jobExport;
     }
+    /**
+     * 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`.
+     */
+    async exportExecution(jobId, workflowTopic, options = {}) {
+        const raw = await this.export(jobId);
+        const execution = this.transformToExecution(raw, jobId, workflowTopic, options);
+        if (options.mode === 'verbose') {
+            const maxDepth = options.max_depth ?? 5;
+            execution.children = await this.fetchChildren(raw, workflowTopic, options, 1, maxDepth);
+        }
+        return execution;
+    }
+    /**
+     * Pure transformation: convert a raw DurableJobExport into a
+     * Temporal-compatible WorkflowExecution event history.
+     */
+    transformToExecution(raw, workflowId, workflowTopic, options) {
+        const events = [];
+        let nextId = 1;
+        // ── Extract timing from state metadata ─────────────────────────
+        const state = raw.state;
+        const metadata = state?.output?.metadata ?? state?.metadata;
+        const stateData = state?.output?.data ?? state?.data;
+        const jobCreated = metadata?.jc ?? stateData?.jc ?? metadata?.ac;
+        const jobUpdated = metadata?.ju ?? stateData?.ju ?? metadata?.au;
+        const startTime = parseTimestamp(jobCreated);
+        const closeTime = parseTimestamp(jobUpdated);
+        // ── Synthetic workflow_execution_started ─────────────────────────
+        if (startTime) {
+            events.push(makeEvent(nextId++, 'workflow_execution_started', 'workflow', startTime, null, false, {
+                kind: 'workflow_execution_started',
+                workflow_type: workflowTopic,
+                task_queue: workflowTopic,
+                input: options.omit_results ? undefined : raw.data,
+            }));
+        }
+        // ── Transform timeline entries ───────────────────────────────
+        const timeline = raw.timeline || [];
+        for (const entry of timeline) {
+            const operation = extractOperation(entry.key);
+            const val = (typeof entry.value === 'object' && entry.value !== null)
+                ? entry.value
+                : null;
+            const ac = val?.ac;
+            const au = val?.au;
+            const acIso = parseTimestamp(ac);
+            const auIso = parseTimestamp(au);
+            const dur = computeDuration(ac, au);
+            const hasError = val != null && '$error' in val;
+            switch (operation) {
+                case 'proxy': {
+                    const name = extractActivityName(val);
+                    const isSys = isSystemActivity(name);
+                    if (options.exclude_system && isSys)
+                        break;
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'activity_task_scheduled', 'activity', acIso, null, isSys, {
+                            kind: 'activity_task_scheduled',
+                            activity_type: name,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        if (hasError) {
+                            events.push(makeEvent(nextId++, 'activity_task_failed', 'activity', auIso, dur, isSys, {
+                                kind: 'activity_task_failed',
+                                activity_type: name,
+                                failure: val?.$error,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                        else {
+                            events.push(makeEvent(nextId++, 'activity_task_completed', 'activity', auIso, dur, isSys, {
+                                kind: 'activity_task_completed',
+                                activity_type: name,
+                                result: options.omit_results ? undefined : val?.data,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                    }
+                    break;
+                }
+                case 'child': {
+                    const childId = extractChildWorkflowId(val);
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'child_workflow_execution_started', 'child_workflow', acIso, null, false, {
+                            kind: 'child_workflow_execution_started',
+                            child_workflow_id: childId,
+                            awaited: true,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        if (hasError) {
+                            events.push(makeEvent(nextId++, 'child_workflow_execution_failed', 'child_workflow', auIso, dur, false, {
+                                kind: 'child_workflow_execution_failed',
+                                child_workflow_id: childId,
+                                failure: val?.$error,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                        else {
+                            events.push(makeEvent(nextId++, 'child_workflow_execution_completed', 'child_workflow', auIso, dur, false, {
+                                kind: 'child_workflow_execution_completed',
+                                child_workflow_id: childId,
+                                result: options.omit_results ? undefined : val?.data,
+                                timeline_key: entry.key,
+                                execution_index: entry.index,
+                            }));
+                        }
+                    }
+                    break;
+                }
+                case 'start': {
+                    const childId = extractChildWorkflowId(val);
+                    const ts = acIso || auIso;
+                    if (ts) {
+                        events.push(makeEvent(nextId++, 'child_workflow_execution_started', 'child_workflow', ts, null, false, {
+                            kind: 'child_workflow_execution_started',
+                            child_workflow_id: childId,
+                            awaited: false,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                case 'wait': {
+                    const signalName = val?.id
+                        || val?.data?.id
+                        || val?.data?.data?.id
+                        || `signal-${entry.index}`;
+                    const ts = auIso || acIso;
+                    if (ts) {
+                        events.push(makeEvent(nextId++, 'workflow_execution_signaled', 'signal', ts, dur, false, {
+                            kind: 'workflow_execution_signaled',
+                            signal_name: signalName,
+                            input: options.omit_results ? undefined : val?.data?.data,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                case 'sleep': {
+                    if (acIso) {
+                        events.push(makeEvent(nextId++, 'timer_started', 'timer', acIso, null, false, {
+                            kind: 'timer_started',
+                            duration_ms: dur ?? undefined,
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    if (auIso) {
+                        events.push(makeEvent(nextId++, 'timer_fired', 'timer', auIso, dur, false, {
+                            kind: 'timer_fired',
+                            timeline_key: entry.key,
+                            execution_index: entry.index,
+                        }));
+                    }
+                    break;
+                }
+                // Unknown operation types are silently skipped (forward-compatible)
+            }
+        }
+        // ── Determine status ─────────────────────────────────────────
+        const isDone = stateData?.done === true;
+        const hasError = !!stateData?.$error;
+        const status = mapStatus(raw.status, isDone, hasError);
+        // ── Extract workflow result ──────────────────────────────────
+        const result = stateData?.response ?? (raw.data && Object.keys(raw.data).length > 0 ? raw.data : null);
+        // ── Synthetic workflow_execution_completed / failed ───────────
+        if (status === 'completed' && closeTime) {
+            const totalDur = startTime
+                ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+                : null;
+            events.push(makeEvent(nextId++, 'workflow_execution_completed', 'workflow', closeTime, totalDur, false, {
+                kind: 'workflow_execution_completed',
+                result: options.omit_results ? undefined : result,
+            }));
+        }
+        else if (status === 'failed' && closeTime) {
+            const totalDur = startTime
+                ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+                : null;
+            events.push(makeEvent(nextId++, 'workflow_execution_failed', 'workflow', closeTime, totalDur, false, {
+                kind: 'workflow_execution_failed',
+                failure: stateData?.err,
+            }));
+        }
+        // ── Sort chronologically ─────────────────────────────────────
+        events.sort((a, b) => {
+            const cmp = a.event_time.localeCompare(b.event_time);
+            return cmp !== 0 ? cmp : a.event_id - b.event_id;
+        });
+        // ── Re-number event IDs after sort ───────────────────────────
+        for (let i = 0; i < events.length; i++) {
+            events[i].event_id = i + 1;
+        }
+        // ── Back-references (Temporal-compatible) ────────────────────
+        const scheduledMap = new Map();
+        const initiatedMap = new Map();
+        for (const e of events) {
+            const attrs = e.attributes;
+            if (e.event_type === 'activity_task_scheduled' && attrs.timeline_key) {
+                scheduledMap.set(attrs.timeline_key, e.event_id);
+            }
+            if (e.event_type === 'child_workflow_execution_started' && attrs.timeline_key) {
+                initiatedMap.set(attrs.timeline_key, e.event_id);
+            }
+            if ((e.event_type === 'activity_task_completed' || e.event_type === 'activity_task_failed') && attrs.timeline_key) {
+                attrs.scheduled_event_id = scheduledMap.get(attrs.timeline_key) ?? null;
+            }
+            if ((e.event_type === 'child_workflow_execution_completed' || e.event_type === 'child_workflow_execution_failed') && attrs.timeline_key) {
+                attrs.initiated_event_id = initiatedMap.get(attrs.timeline_key) ?? null;
+            }
+        }
+        // ── Compute total duration ───────────────────────────────────
+        const totalDuration = (startTime && closeTime)
+            ? new Date(closeTime).getTime() - new Date(startTime).getTime()
+            : null;
+        return {
+            workflow_id: workflowId,
+            workflow_type: workflowTopic,
+            task_queue: workflowTopic,
+            status,
+            start_time: startTime,
+            close_time: (status !== 'running') ? closeTime : null,
+            duration_ms: totalDuration,
+            result,
+            events,
+            summary: computeSummary(events),
+        };
+    }
+    /**
+     * Recursively fetch child workflow executions for verbose mode.
+     */
+    async fetchChildren(raw, workflowTopic, options, depth, maxDepth) {
+        if (depth >= maxDepth)
+            return [];
+        const children = [];
+        const timeline = raw.timeline || [];
+        for (const entry of timeline) {
+            const operation = extractOperation(entry.key);
+            if (operation !== 'child' && operation !== 'start')
+                continue;
+            const val = (typeof entry.value === 'object' && entry.value !== null)
+                ? entry.value
+                : null;
+            const childJobId = val?.job_id;
+            if (!childJobId || typeof childJobId !== 'string')
+                continue;
+            try {
+                const childRaw = await this.export(childJobId);
+                const childTopic = childRaw.data?.workflowTopic ?? workflowTopic;
+                const childExecution = this.transformToExecution(childRaw, childJobId, childTopic, options);
+                if (options.mode === 'verbose') {
+                    childExecution.children = await this.fetchChildren(childRaw, childTopic, options, depth + 1, maxDepth);
+                }
+                children.push(childExecution);
+            }
+            catch {
+                // Child job may have expired or been cleaned up
+            }
+        }
+        return children;
+    }
     /**
      * Inflates the job data into a DurableJobExport object
      * @param jobHash - the job data

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

@@ -1,5 +1,5 @@
 import { HotMesh } from '../hotmesh';
-import { DurableJobExport, ExportOptions } from '../../types/exporter';
+import { DurableJobExport, ExportOptions, ExecutionExportOptions, WorkflowExecution } from '../../types/exporter';
 import { JobInterruptOptions } from '../../types/job';
 import { StreamError } from '../../types/stream';
 import { ExporterService } from './exporter';
@@ -44,6 +44,17 @@ export declare class WorkflowHandleService {
      * Exports the workflow state to a JSON object.
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
+    /**
+     * Exports the workflow as a Temporal-like execution event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list with workflow lifecycle, activity, child workflow,
+     * timer, and signal events.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their full execution histories as nested `children`.
+     */
+    exportExecution(options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**
      * Sends a signal to the workflow. This is a way to send
      * a message to a workflow that is paused due to having

package/build/services/durable/handle.js

@@ -43,6 +43,19 @@ class WorkflowHandleService {
     async export(options) {
         return this.exporter.export(this.workflowId, options);
     }
+    /**
+     * Exports the workflow as a Temporal-like execution event history.
+     *
+     * **Sparse mode** (default): transforms the main workflow's timeline
+     * into a flat event list with workflow lifecycle, activity, child workflow,
+     * timer, and signal events.
+     *
+     * **Verbose mode**: recursively fetches child workflow jobs and attaches
+     * their full execution histories as nested `children`.
+     */
+    async exportExecution(options) {
+        return this.exporter.exportExecution(this.workflowId, this.workflowTopic, options);
+    }
     /**
      * Sends a signal to the workflow. This is a way to send
      * a message to a workflow that is paused due to having

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

@@ -182,6 +182,7 @@ const KVTables = (context) => ({
                 created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
                 expired_at TIMESTAMP WITH TIME ZONE,
+                pruned_at TIMESTAMP WITH TIME ZONE,
                 is_live BOOLEAN DEFAULT TRUE,
                 PRIMARY KEY (id)
               ) PARTITION BY HASH (id);
@@ -214,8 +215,12 @@ const KVTables = (context) => ({
               ON ${fullTableName} (entity, status);
             `);
                         await client.query(`
-              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_expired_at 
+              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_expired_at
               ON ${fullTableName} (expired_at);
+            `);
+                        await client.query(`
+              CREATE INDEX IF NOT EXISTS idx_${tableDef.name}_pruned_at
+              ON ${fullTableName} (pruned_at) WHERE pruned_at IS NULL;
             `);
                         // Create function to update is_live flag in the schema
                         await client.query(`

package/build/types/dba.d.ts

@@ -31,7 +31,7 @@ export interface PruneOptions {
     /**
      * If true, hard-deletes expired jobs older than the retention window.
      * FK CASCADE on `jobs_attributes` automatically removes associated
-     * attribute rows.
+     * attribute rows. When `entities` is set, only matching jobs are deleted.
      * @default true
      */
     jobs?: boolean;
@@ -42,13 +42,35 @@ export interface PruneOptions {
      */
     streams?: boolean;
     /**
-     * If true, strips execution-artifact attributes (`adata`, `hmark`,
-     * `jmark`, `status`, `other`) from completed jobs (status = 0),
-     * retaining only `jdata` (workflow return data) and `udata`
-     * (user-searchable data).
+     * If true, strips execution-artifact attributes from completed,
+     * un-pruned jobs. Preserves `jdata` (return data), `udata`
+     * (searchable data), and `jmark` (timeline/event history for
+     * Temporal-compatible export). See `keepHmark` for `hmark`.
      * @default false
      */
     attributes?: boolean;
+    /**
+     * Entity allowlist. When provided, only jobs whose `entity` column
+     * matches one of these values are eligible for pruning/stripping.
+     * Jobs with `entity IS NULL` are excluded unless `pruneTransient`
+     * is also true.
+     * @default undefined (all entities)
+     */
+    entities?: string[];
+    /**
+     * If true, hard-deletes expired jobs where `entity IS NULL`
+     * (transient workflow runs). Must also satisfy the retention
+     * window (`expire`).
+     * @default false
+     */
+    pruneTransient?: boolean;
+    /**
+     * If true, `hmark` attributes are preserved during stripping
+     * (along with `jdata`, `udata`, and `jmark`). If false, `hmark`
+     * rows are stripped.
+     * @default false
+     */
+    keepHmark?: boolean;
 }
 /**
  * Result returned by `DBA.prune()`, providing deletion
@@ -61,4 +83,8 @@ export interface PruneResult {
     streams: number;
     /** Number of execution-artifact attribute rows stripped from completed jobs */
     attributes: number;
+    /** Number of transient (entity IS NULL) job rows hard-deleted */
+    transient: number;
+    /** Number of jobs marked as pruned (pruned_at set) */
+    marked: number;
 }

package/build/types/exporter.d.ts

@@ -79,3 +79,130 @@ export interface JobExport {
     process: StringAnyType;
     status: string;
 }
+export type ExportMode = 'sparse' | 'verbose';
+export type WorkflowEventType = 'workflow_execution_started' | 'workflow_execution_completed' | 'workflow_execution_failed' | 'activity_task_scheduled' | 'activity_task_completed' | 'activity_task_failed' | 'child_workflow_execution_started' | 'child_workflow_execution_completed' | 'child_workflow_execution_failed' | 'timer_started' | 'timer_fired' | 'workflow_execution_signaled';
+export type WorkflowEventCategory = 'workflow' | 'activity' | 'child_workflow' | 'timer' | 'signal';
+export interface WorkflowExecutionStartedAttributes {
+    kind: 'workflow_execution_started';
+    workflow_type: string;
+    task_queue: string;
+    input?: any;
+}
+export interface WorkflowExecutionCompletedAttributes {
+    kind: 'workflow_execution_completed';
+    result?: any;
+}
+export interface WorkflowExecutionFailedAttributes {
+    kind: 'workflow_execution_failed';
+    failure?: string;
+}
+export interface ActivityTaskScheduledAttributes {
+    kind: 'activity_task_scheduled';
+    activity_type: string;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ActivityTaskCompletedAttributes {
+    kind: 'activity_task_completed';
+    activity_type: string;
+    result?: any;
+    scheduled_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ActivityTaskFailedAttributes {
+    kind: 'activity_task_failed';
+    activity_type: string;
+    failure?: any;
+    scheduled_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionStartedAttributes {
+    kind: 'child_workflow_execution_started';
+    child_workflow_id: string;
+    awaited: boolean;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionCompletedAttributes {
+    kind: 'child_workflow_execution_completed';
+    child_workflow_id: string;
+    result?: any;
+    initiated_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface ChildWorkflowExecutionFailedAttributes {
+    kind: 'child_workflow_execution_failed';
+    child_workflow_id: string;
+    failure?: any;
+    initiated_event_id?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface TimerStartedAttributes {
+    kind: 'timer_started';
+    duration_ms?: number;
+    timeline_key: string;
+    execution_index: number;
+}
+export interface TimerFiredAttributes {
+    kind: 'timer_fired';
+    timeline_key: string;
+    execution_index: number;
+}
+export interface WorkflowExecutionSignaledAttributes {
+    kind: 'workflow_execution_signaled';
+    signal_name: string;
+    input?: any;
+    timeline_key: string;
+    execution_index: number;
+}
+export type WorkflowEventAttributes = WorkflowExecutionStartedAttributes | WorkflowExecutionCompletedAttributes | WorkflowExecutionFailedAttributes | ActivityTaskScheduledAttributes | ActivityTaskCompletedAttributes | ActivityTaskFailedAttributes | ChildWorkflowExecutionStartedAttributes | ChildWorkflowExecutionCompletedAttributes | ChildWorkflowExecutionFailedAttributes | TimerStartedAttributes | TimerFiredAttributes | WorkflowExecutionSignaledAttributes;
+export interface WorkflowExecutionEvent {
+    event_id: number;
+    event_type: WorkflowEventType;
+    category: WorkflowEventCategory;
+    event_time: string;
+    duration_ms: number | null;
+    is_system: boolean;
+    attributes: WorkflowEventAttributes;
+}
+export interface WorkflowExecutionSummary {
+    total_events: number;
+    activities: {
+        total: number;
+        completed: number;
+        failed: number;
+        system: number;
+        user: number;
+    };
+    child_workflows: {
+        total: number;
+        completed: number;
+        failed: number;
+    };
+    timers: number;
+    signals: number;
+}
+export type WorkflowExecutionStatus = 'running' | 'completed' | 'failed';
+export interface WorkflowExecution {
+    workflow_id: string;
+    workflow_type: string;
+    task_queue: string;
+    status: WorkflowExecutionStatus;
+    start_time: string | null;
+    close_time: string | null;
+    duration_ms: number | null;
+    result: any;
+    events: WorkflowExecutionEvent[];
+    summary: WorkflowExecutionSummary;
+    children?: WorkflowExecution[];
+}
+export interface ExecutionExportOptions {
+    mode?: ExportMode;
+    exclude_system?: boolean;
+    omit_results?: boolean;
+    max_depth?: number;
+}

package/build/types/index.d.ts

@@ -6,7 +6,7 @@ export { CollationFaultType, CollationStage } from './collator';
 export { ActivityConfig, ActivityInterceptor, ActivityInterceptorContext, ActivityWorkflowDataType, ChildResponseType, ClientConfig, ClientWorkflow, ContextType, Connection, ProxyResponseType, ProxyType, Registry, SignalOptions, FindJobsOptions, FindOptions, FindWhereOptions, FindWhereQuery, HookOptions, SearchResults, WorkflowConfig, WorkerConfig, WorkerOptions, WorkflowContext, WorkflowSearchOptions, WorkflowSearchSchema, WorkflowDataType, WorkflowOptions, WorkflowInterceptor, InterceptorRegistry, } from './durable';
 export { PruneOptions, PruneResult, } from './dba';
 export { DurableChildErrorType, DurableProxyErrorType, DurableSleepErrorType, DurableWaitForAllErrorType, DurableWaitForErrorType, } from './error';
-export { ActivityAction, DependencyExport, DurableJobExport, ExportCycles, ExportItem, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline, } from './exporter';
+export { ActivityAction, DependencyExport, DurableJobExport, ExecutionExportOptions, ExportCycles, ExportItem, ExportMode, ExportOptions, ExportTransitions, JobAction, JobExport, JobActionExport, JobTimeline, WorkflowEventAttributes, WorkflowEventCategory, WorkflowEventType, WorkflowExecution, WorkflowExecutionEvent, WorkflowExecutionStatus, WorkflowExecutionSummary, } from './exporter';
 export { HookCondition, HookConditions, HookGate, HookInterface, HookRule, HookRules, HookSignal, } from './hook';
 export { HotMesh, HotMeshEngine, HotMeshWorker, HotMeshSettings, HotMeshApp, HotMeshApps, HotMeshConfig, HotMeshManifest, HotMeshGraph, KeyType, KeyStoreParams, ScoutType, } from './hotmesh';
 export { ILogger, LogLevel } from './logger';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.10.1",
+  "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",