@arke-institute/rhiza 0.1.0

package/dist/index.js

@@ -0,0 +1,52 @@
+/**
+ * @arke-institute/rhiza
+ *
+ * Types, pure logic, and SDK utilities for Arke workflow protocol.
+ * Workers use rhiza for types, validation, and workflow execution.
+ *
+ * Naming:
+ * - Rhiza (ῥίζα) = root, the workflow definition
+ * - Klados (κλάδος) = branch, an individual action
+ *
+ * The library provides:
+ * - Types: Entity types, request/response types, log types
+ * - Validation: Pure validation functions for klados/rhiza properties
+ * - Handoff (pure): Route matching, target resolution, gather state transforms
+ * - Handoff (SDK): Invocation, scatter/gather with CAS, orchestration
+ * - Logging: In-memory logger and API writers
+ * - Utilities: ID generation
+ */
+export { isEntityRef, ref } from './types/refs';
+// ============================================================================
+// Validation
+// ============================================================================
+export { validateKladosProperties, } from './validation/validate-klados';
+export { validateRhizaProperties } from './validation/validate-rhiza';
+// ============================================================================
+// Handoff - Pure functions for route matching, target resolution, gather
+// ============================================================================
+export { evaluateWhere, matchRoute } from './handoff/route';
+export { resolveTarget } from './handoff/target';
+export { findGatherTarget } from './handoff/scatter';
+export { completeBatchSlot, errorBatchSlot, } from './handoff/gather';
+// ============================================================================
+// Handoff - SDK utilities for execution (requires @arke-institute/sdk)
+// ============================================================================
+export { discoverTargetType, invokeTarget, invokeKlados, invokeRhiza, } from './handoff/invoke';
+export { createScatterBatch, } from './handoff/scatter-api';
+export { completeBatchSlotWithCAS, errorBatchSlotWithCAS, } from './handoff/gather-api';
+export { interpretThen, } from './handoff/interpret';
+// ============================================================================
+// Logging - In-memory logger and API writers
+// ============================================================================
+export { KladosLogger } from './logging/logger';
+export { writeKladosLog, updateLogWithHandoffs, updateLogStatus, } from './logging/writer';
+// ============================================================================
+// Worker Utilities - High-level abstractions for klados workers
+// ============================================================================
+export { KladosJob, KladosErrorCode, createKladosError, toKladosError, isKladosError, failKlados, } from './worker';
+// ============================================================================
+// Utilities
+// ============================================================================
+export { generateId } from './utils/id';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA4BH,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAyChD,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E,OAAO,EACL,wBAAwB,GAIzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,+EAA+E;AAC/E,yEAAyE;AACzE,+EAA+E;AAE/E,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,iBAAiB,EACjB,cAAc,GAIf,MAAM,kBAAkB,CAAC;AAE1B,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAE/E,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACZ,WAAW,GAGZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,GAGnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,GAGtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,aAAa,GAId,MAAM,qBAAqB,CAAC;AAE7B,+EAA+E;AAC/E,6CAA6C;AAC7C,+EAA+E;AAE/E,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,eAAe,GAIhB,MAAM,kBAAkB,CAAC;AAE1B,+EAA+E;AAC/E,gEAAgE;AAChE,+EAA+E;AAE/E,OAAO,EACL,SAAS,EAGT,eAAe,EAGf,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,UAAU,GAEX,MAAM,UAAU,CAAC;AAElB,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/logging/index.d.ts

@@ -0,0 +1,4 @@
+export { KladosLogger } from './logger';
+export { writeKladosLog, updateLogWithHandoffs, updateLogStatus, } from './writer';
+export type { WriteLogOptions, WriteLogResult, LogError } from './writer';
+//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/logging/index.js

@@ -0,0 +1,3 @@
+export { KladosLogger } from './logger';
+export { writeKladosLog, updateLogWithHandoffs, updateLogStatus, } from './writer';
+//# sourceMappingURL=index.js.map

package/dist/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,eAAe,GAChB,MAAM,UAAU,CAAC"}

package/dist/logging/logger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * KladosLogger - In-memory log message collector
+ *
+ * Collects log messages during klados execution.
+ * Messages are written to the log entry when execution completes.
+ */
+import type { LogMessage } from '../types';
+/**
+ * KladosLogger - In-memory log message collector
+ *
+ * Usage:
+ * ```typescript
+ * const logger = new KladosLogger();
+ * logger.info('Starting processing', { target: entityId });
+ * logger.success('Processing complete');
+ *
+ * // Get messages for log entry
+ * const messages = logger.getMessages();
+ * ```
+ */
+export declare class KladosLogger {
+    private messages;
+    /**
+     * Log an info message
+     */
+    info(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a warning message
+     */
+    warning(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Log a success message
+     */
+    success(message: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Add a log message
+     */
+    private add;
+    /**
+     * Get all collected messages
+     */
+    getMessages(): LogMessage[];
+    /**
+     * Clear all messages
+     */
+    clear(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAoB;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI/D;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIlE;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhE;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIlE;;OAEG;IACH,OAAO,CAAC,GAAG;IAaX;;OAEG;IACH,WAAW,IAAI,UAAU,EAAE;IAI3B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/logging/logger.js

@@ -0,0 +1,70 @@
+/**
+ * KladosLogger - In-memory log message collector
+ *
+ * Collects log messages during klados execution.
+ * Messages are written to the log entry when execution completes.
+ */
+/**
+ * KladosLogger - In-memory log message collector
+ *
+ * Usage:
+ * ```typescript
+ * const logger = new KladosLogger();
+ * logger.info('Starting processing', { target: entityId });
+ * logger.success('Processing complete');
+ *
+ * // Get messages for log entry
+ * const messages = logger.getMessages();
+ * ```
+ */
+export class KladosLogger {
+    messages = [];
+    /**
+     * Log an info message
+     */
+    info(message, metadata) {
+        this.add('info', message, metadata);
+    }
+    /**
+     * Log a warning message
+     */
+    warning(message, metadata) {
+        this.add('warning', message, metadata);
+    }
+    /**
+     * Log an error message
+     */
+    error(message, metadata) {
+        this.add('error', message, metadata);
+    }
+    /**
+     * Log a success message
+     */
+    success(message, metadata) {
+        this.add('success', message, metadata);
+    }
+    /**
+     * Add a log message
+     */
+    add(level, message, metadata) {
+        this.messages.push({
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            metadata,
+        });
+    }
+    /**
+     * Get all collected messages
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Clear all messages
+     */
+    clear() {
+        this.messages = [];
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logging/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAY;IACf,QAAQ,GAAiB,EAAE,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAe,EAAE,QAAkC;QACtD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,OAAe,EAAE,QAAkC;QACzD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,QAAkC;QACvD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,OAAe,EAAE,QAAkC;QACzD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACK,GAAG,CACT,KAA0B,EAC1B,OAAe,EACf,QAAkC;QAElC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,KAAK;YACL,OAAO;YACP,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,QAAQ;SACT,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/logging/writer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Log Writer - SDK utilities for writing klados logs
+ *
+ * Uses the SDK to write log entries to the job collection.
+ * CAS retry is handled by the SDK's withCasRetry utility.
+ */
+import type { ArkeClient } from '@arke-institute/sdk';
+import type { KladosLogEntry, LogMessage, HandoffRecord } from '../types';
+/**
+ * Options for writing a klados log
+ */
+export interface WriteLogOptions {
+    /** Arke client */
+    client: ArkeClient;
+    /** Job collection ID */
+    jobCollectionId: string;
+    /** Klados log entry data */
+    entry: KladosLogEntry;
+    /** Human-readable log messages */
+    messages: LogMessage[];
+    /** Agent info */
+    agentId: string;
+    agentVersion: string;
+}
+/**
+ * Result of writing a klados log
+ */
+export interface WriteLogResult {
+    /** Log entity ID (the generated log ID) */
+    logId: string;
+    /** Log file entity ID (the actual file entity) */
+    fileId: string;
+}
+/**
+ * Write a klados log entry to the job collection
+ *
+ * Creates an entity with the log data and adds relationships
+ * for chain traversal. The from_logs array is stored both in
+ * properties and as received_from relationships.
+ */
+export declare function writeKladosLog(options: WriteLogOptions): Promise<WriteLogResult>;
+/**
+ * Update log entry with handoff records
+ *
+ * Called after handoffs are made to record what was invoked.
+ * Uses CAS retry for concurrent safety.
+ */
+export declare function updateLogWithHandoffs(client: ArkeClient, logFileId: string, handoffs: HandoffRecord[]): Promise<void>;
+/**
+ * Log error info for status updates
+ */
+export interface LogError {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Update log entry status (e.g., to done or error)
+ *
+ * Uses CAS retry for concurrent safety.
+ */
+export declare function updateLogStatus(client: ArkeClient, logFileId: string, status: 'running' | 'done' | 'error', logError?: LogError): Promise<void>;
+//# sourceMappingURL=writer.d.ts.map

package/dist/logging/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/logging/writer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EACV,cAAc,EAEd,UAAU,EACV,aAAa,EACd,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IAEnB,wBAAwB;IACxB,eAAe,EAAE,MAAM,CAAC;IAExB,4BAA4B;IAC5B,KAAK,EAAE,cAAc,CAAC;IAEtB,kCAAkC;IAClC,QAAQ,EAAE,UAAU,EAAE,CAAC;IAEvB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IAEd,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAoFzB;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,EACpC,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/logging/writer.js

@@ -0,0 +1,160 @@
+/**
+ * Log Writer - SDK utilities for writing klados logs
+ *
+ * Uses the SDK to write log entries to the job collection.
+ * CAS retry is handled by the SDK's withCasRetry utility.
+ */
+import { withCasRetry } from '@arke-institute/sdk';
+/**
+ * Write a klados log entry to the job collection
+ *
+ * Creates an entity with the log data and adds relationships
+ * for chain traversal. The from_logs array is stored both in
+ * properties and as received_from relationships.
+ */
+export async function writeKladosLog(options) {
+    const { client, jobCollectionId, entry, messages, agentId, agentVersion, } = options;
+    // Build the job log structure
+    const jobLog = {
+        entry,
+        agent_id: agentId,
+        agent_version: agentVersion,
+        messages,
+    };
+    // 1. Create entity with log data
+    const { data: logEntity, error: createError } = await client.api.POST('/entities', {
+        body: {
+            type: 'klados_log',
+            collection: jobCollectionId,
+            properties: {
+                rhiza_id: entry.rhiza_id,
+                klados_id: entry.klados_id,
+                job_id: entry.job_id,
+                status: entry.status,
+                log_data: jobLog,
+            },
+        },
+    });
+    if (createError || !logEntity) {
+        throw new Error(`Failed to create log entity: ${createError?.error || 'Unknown error'}`);
+    }
+    const logEntityId = logEntity.id;
+    // 2. Build relationships for received_from chain traversal
+    const relationships = [];
+    // Add received_from relationships for graph traversal
+    // These mirror the from_logs array in the entry properties
+    if (entry.received.from_logs && entry.received.from_logs.length > 0) {
+        for (const parentLogId of entry.received.from_logs) {
+            relationships.push({
+                predicate: 'received_from',
+                peer: parentLogId,
+                direction: 'outgoing',
+            });
+        }
+    }
+    // 3. Add relationships to the log entity if needed (CAS retry)
+    if (relationships.length > 0) {
+        await withCasRetry({
+            getTip: async () => {
+                const { data, error } = await client.api.GET('/entities/{id}/tip', {
+                    params: { path: { id: logEntityId } },
+                });
+                if (error || !data)
+                    throw new Error('Failed to get log entity tip');
+                return data.cid;
+            },
+            update: async (tip) => {
+                return client.api.PUT('/entities/{id}', {
+                    params: { path: { id: logEntityId } },
+                    body: {
+                        expect_tip: tip,
+                        relationships_add: relationships,
+                    },
+                });
+            },
+        }, { concurrency: 100 });
+    }
+    return { logId: entry.id, fileId: logEntityId };
+}
+/**
+ * Update log entry with handoff records
+ *
+ * Called after handoffs are made to record what was invoked.
+ * Uses CAS retry for concurrent safety.
+ */
+export async function updateLogWithHandoffs(client, logFileId, handoffs) {
+    await withCasRetry({
+        getTip: async () => {
+            const { data, error } = await client.api.GET('/entities/{id}/tip', {
+                params: { path: { id: logFileId } },
+            });
+            if (error || !data)
+                throw new Error('Failed to get log tip');
+            return data.cid;
+        },
+        update: async (tip) => {
+            // Get current entity to merge with existing data
+            const { data: entity, error: getError } = await client.api.GET('/entities/{id}', {
+                params: { path: { id: logFileId } },
+            });
+            if (getError || !entity) {
+                throw new Error('Failed to get log entity');
+            }
+            const logData = entity.properties.log_data;
+            logData.entry.handoffs = handoffs;
+            return client.api.PUT('/entities/{id}', {
+                params: { path: { id: logFileId } },
+                body: {
+                    expect_tip: tip,
+                    properties: {
+                        ...entity.properties,
+                        log_data: logData,
+                    },
+                },
+            });
+        },
+    }, { concurrency: 10 });
+}
+/**
+ * Update log entry status (e.g., to done or error)
+ *
+ * Uses CAS retry for concurrent safety.
+ */
+export async function updateLogStatus(client, logFileId, status, logError) {
+    await withCasRetry({
+        getTip: async () => {
+            const { data, error } = await client.api.GET('/entities/{id}/tip', {
+                params: { path: { id: logFileId } },
+            });
+            if (error || !data)
+                throw new Error('Failed to get log tip');
+            return data.cid;
+        },
+        update: async (tip) => {
+            const { data: entity, error: getError } = await client.api.GET('/entities/{id}', {
+                params: { path: { id: logFileId } },
+            });
+            if (getError || !entity) {
+                throw new Error('Failed to get log entity');
+            }
+            const logData = entity.properties.log_data;
+            logData.entry.status = status;
+            logData.entry.completed_at = new Date().toISOString();
+            if (logError) {
+                logData.entry.error = logError;
+            }
+            return client.api.PUT('/entities/{id}', {
+                params: { path: { id: logFileId } },
+                body: {
+                    expect_tip: tip,
+                    properties: {
+                        ...entity.properties,
+                        status, // Also update top-level for easy querying
+                        log_data: logData,
+                    },
+                },
+            });
+        },
+    }, { concurrency: 10 });
+}
+//# sourceMappingURL=writer.js.map

package/dist/logging/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../src/logging/writer.ts"],"names":[],"mappings":"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"}

package/dist/resume/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Resume Module
+ *
+ * Functions for resuming failed workflow executions.
+ * Resume allows retrying failed jobs while preserving context.
+ */
+import type { KladosLogEntry } from '../types';
+import type { MockArkeClient } from '../__tests__/fixtures/mock-client';
+/**
+ * Options for resuming a workflow
+ */
+export interface ResumeOptions {
+    /** Maximum number of jobs to resume */
+    maxJobs?: number;
+    /** Only resume these specific job IDs */
+    jobIds?: string[];
+}
+/**
+ * Information about a resumed job
+ */
+export interface ResumedJob {
+    originalJobId: string;
+    newJobId: string;
+    kladosId: string;
+    errorLogId: string;
+    targetEntityId: string;
+}
+/**
+ * Result of resuming a workflow
+ */
+export interface ResumeResult {
+    resumed: number;
+    skipped: number;
+    jobs: ResumedJob[];
+}
+/**
+ * Error summary for canResume
+ */
+export interface ErrorSummary {
+    jobId: string;
+    kladosId: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Result of checking if a workflow can be resumed
+ */
+export interface CanResumeResult {
+    canResume: boolean;
+    totalErrors: number;
+    retryableCount: number;
+    nonRetryableCount: number;
+    errors?: ErrorSummary[];
+}
+/**
+ * Resume a workflow by retrying failed jobs
+ *
+ * Finds all error leaves in the log chain and re-invokes them.
+ * Only retries jobs marked as retryable.
+ *
+ * @param client - The Arke client
+ * @param logs - The log chain for the workflow
+ * @param options - Resume options
+ * @returns Resume result with count and job details
+ */
+export declare function resumeWorkflow(client: MockArkeClient, logs: KladosLogEntry[], options?: ResumeOptions): Promise<ResumeResult>;
+/**
+ * Check if a workflow can be resumed
+ *
+ * Analyzes the log chain to find retryable errors.
+ *
+ * @param logs - The log chain for the workflow
+ * @returns Information about resume possibility
+ */
+export declare function canResume(logs: KladosLogEntry[]): CanResumeResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/resume/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resume/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAGxE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB;AASD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,cAAc,EAAE,EACtB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAsEvB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,eAAe,CAqBjE"}

package/dist/resume/index.js

@@ -0,0 +1,110 @@
+/**
+ * Resume Module
+ *
+ * Functions for resuming failed workflow executions.
+ * Resume allows retrying failed jobs while preserving context.
+ */
+import { findErrorLeaves } from '../traverse';
+/**
+ * Generate a new job ID for resume
+ */
+function generateJobId() {
+    return `job-resume-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Resume a workflow by retrying failed jobs
+ *
+ * Finds all error leaves in the log chain and re-invokes them.
+ * Only retries jobs marked as retryable.
+ *
+ * @param client - The Arke client
+ * @param logs - The log chain for the workflow
+ * @param options - Resume options
+ * @returns Resume result with count and job details
+ */
+export async function resumeWorkflow(client, logs, options = {}) {
+    const { maxJobs, jobIds } = options;
+    // Find all error leaves
+    const errorLeaves = findErrorLeaves(logs);
+    // Filter by jobIds if provided
+    let candidates = errorLeaves;
+    if (jobIds && jobIds.length > 0) {
+        const jobIdSet = new Set(jobIds);
+        candidates = errorLeaves.filter((e) => jobIdSet.has(e.log.job_id));
+    }
+    const result = {
+        resumed: 0,
+        skipped: 0,
+        jobs: [],
+    };
+    for (const errorLeaf of candidates) {
+        // Check maxJobs limit
+        if (maxJobs !== undefined && result.resumed >= maxJobs) {
+            result.skipped++;
+            continue;
+        }
+        // Skip non-retryable errors
+        if (!errorLeaf.retryable) {
+            result.skipped++;
+            continue;
+        }
+        // Extract original request from the error log
+        const originalLog = errorLeaf.log;
+        const originalRequest = originalLog.received?.invocation?.request;
+        if (!originalRequest) {
+            // Cannot resume without original request
+            result.skipped++;
+            continue;
+        }
+        // Generate new job ID
+        const newJobId = generateJobId();
+        // Get target entity from original request or received
+        const targetEntityId = originalRequest.target ||
+            originalLog.received?.target ||
+            '';
+        // Re-invoke the klados
+        client.invokeKlados(originalLog.klados_id, {
+            jobId: newJobId,
+            targetEntityId,
+            originalRequest,
+            resumedFrom: originalLog.id,
+        });
+        result.resumed++;
+        result.jobs.push({
+            originalJobId: originalLog.job_id,
+            newJobId,
+            kladosId: originalLog.klados_id,
+            errorLogId: originalLog.id,
+            targetEntityId,
+        });
+    }
+    return result;
+}
+/**
+ * Check if a workflow can be resumed
+ *
+ * Analyzes the log chain to find retryable errors.
+ *
+ * @param logs - The log chain for the workflow
+ * @returns Information about resume possibility
+ */
+export function canResume(logs) {
+    const errorLeaves = findErrorLeaves(logs);
+    const errors = errorLeaves.map((e) => ({
+        jobId: e.log.job_id,
+        kladosId: e.log.klados_id,
+        code: e.log.error?.code ?? 'UNKNOWN',
+        message: e.log.error?.message ?? 'Unknown error',
+        retryable: e.retryable,
+    }));
+    const retryableCount = errors.filter((e) => e.retryable).length;
+    const nonRetryableCount = errors.filter((e) => !e.retryable).length;
+    return {
+        canResume: retryableCount > 0,
+        totalErrors: errors.length,
+        retryableCount,
+        nonRetryableCount,
+        errors: errors.length > 0 ? errors : undefined,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/resume/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resume/index.ts"],"names":[],"mappings":"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"}