@cascade-flow/backend-interface 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# Backend Interface
+
+Abstract persistence layer for workflow orchestration.
+
+## Installation
+
+```bash
+bun install
+```
+
+## Overview
+
+Defines the `Backend` abstract class and schemas for event sourcing architecture.
+
+## Key Components
+
+### Abstract Backend Class
+
+```typescript
+import { Backend } from "@cascade-flow/backend-interface";
+
+class MyBackend extends Backend {
+  // Implement abstract methods
+  async registerWorkflow(registration: WorkflowRegistration) { ... }
+  async appendEvent(workflowSlug: string, runId: string, event: Event) { ... }
+  async loadEvents(workflowSlug: string, runId: string) { ... }
+  // ... other methods
+}
+```
+
+### Schemas
+
+**Event Schemas** (`src/events.ts`):
+- Step events: `StepScheduled`, `StepStarted`, `StepHeartbeat`, `StepCompleted`, `StepFailed`, `StepReclaimed`, `LogEntry`
+- Workflow events: `WorkflowStarted`, `WorkflowInputValidation`, `WorkflowCompleted`, `WorkflowFailed`, `WorkflowResumed`, `WorkflowCancelled`, `RunSubmitted`
+
+**State Schemas** (`src/schemas.ts`):
+- `stepStateSchema` - Step state (computed from events)
+- `runStateSchema` - Run state (computed from events)
+- `workflowMetadataSchema` - Backend-agnostic workflow metadata
+- `stepDefinitionSchema` - Step structure
+
+### Projection Functions
+
+```typescript
+import { projectStepState, projectRunStateFromEvents } from "@cascade-flow/backend-interface";
+
+// Compute current state from events
+const stepState = projectStepState(stepEvents);
+const runState = projectRunStateFromEvents(workflowEvents);
+```
+
+## Event Structure
+
+Events use two-level discrimination:
+1. **Category**: `"workflow"` or `"step"`
+2. **Type**: Event-specific (e.g., `"StepStarted"`, `"WorkflowCompleted"`)
+
+## Implementations
+
+- **FileSystemBackend** - Stores events in `.runs/` directory
+- Custom backends - Implement for databases, cloud storage, etc.
+
+## Exports
+
+```typescript
+// Abstract class
+export { Backend } from "./interface";
+
+// Schemas
+export * from "./schemas";
+export * from "./events";
+
+// Projection
+export { projectStepState, projectRunStateFromEvents } from "./projection";
+
+// Utilities
+export * from "./serialization";
+```

package/dist/analytics-helpers.d.ts

@@ -0,0 +1,51 @@
+import type { StepEvent, WorkflowEvent } from "./events.ts";
+import type { ErrorAnalysis, RetryAnalysis, SchedulingLatency, StepDuration, WorkflowDuration, WorkerStability, Throughput, SuccessRate } from "./analytics.ts";
+/**
+ * Helper functions for computing analytics from events
+ * These are pure functions that can be used by any backend implementation
+ */
+/**
+ * Calculate percentiles from an array of numbers
+ */
+export declare function calculatePercentiles(values: number[]): {
+    count: number;
+    min: number;
+    max: number;
+    average: number;
+    median: number;
+    p95: number;
+    p99: number;
+};
+/**
+ * Compute error analysis from step events
+ */
+export declare function computeErrorAnalysis(stepEvents: StepEvent[], workflowSlug?: string, stepId?: string): ErrorAnalysis;
+/**
+ * Compute retry analysis from step events
+ */
+export declare function computeRetryAnalysis(stepEvents: StepEvent[]): RetryAnalysis;
+/**
+ * Compute scheduling latency from step events
+ */
+export declare function computeSchedulingLatency(stepEvents: StepEvent[], workflowSlug?: string, stepId?: string): SchedulingLatency;
+/**
+ * Compute step duration from step events
+ */
+export declare function computeStepDuration(stepEvents: StepEvent[], workflowSlug?: string, stepId?: string): StepDuration;
+/**
+ * Compute workflow duration from workflow events
+ */
+export declare function computeWorkflowDuration(workflowEvents: WorkflowEvent[], workflowSlug?: string): WorkflowDuration;
+/**
+ * Compute worker stability from step events
+ */
+export declare function computeWorkerStability(stepEvents: StepEvent[]): WorkerStability;
+/**
+ * Compute throughput from events
+ */
+export declare function computeThroughput(stepEvents: StepEvent[], workflowEvents: WorkflowEvent[], timeRangeUs: number, workflowSlug?: string): Throughput;
+/**
+ * Compute success rate from events
+ */
+export declare function computeSuccessRate(stepEvents: StepEvent[], workflowEvents: WorkflowEvent[], workflowSlug?: string, stepId?: string): SuccessRate;
+//# sourceMappingURL=analytics-helpers.d.ts.map

package/dist/analytics-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics-helpers.d.ts","sourceRoot":"","sources":["../src/analytics-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EACT,aAAa,EAQd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,WAAW,EAEZ,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAyBA;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,EAAE,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,aAAa,CAqGf;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,aAAa,CA2F3E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,SAAS,EAAE,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,iBAAiB,CAyCnB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,EAAE,EACvB,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,YAAY,CAsBd;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,CAAC,EAAE,MAAM,GACpB,gBAAgB,CAyBlB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,eAAe,CAyC/E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,EAAE,EACvB,cAAc,EAAE,aAAa,EAAE,EAC/B,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,GACpB,UAAU,CAiCZ;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,SAAS,EAAE,EACvB,cAAc,EAAE,aAAa,EAAE,EAC/B,YAAY,CAAC,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,WAAW,CAiCb"}

package/dist/analytics.d.ts

@@ -0,0 +1,338 @@
+import { z } from "zod";
+/**
+ * Error breakdown by failure reason
+ */
+export declare const errorBreakdownSchema: z.ZodObject<{
+    failureReason: z.ZodEnum<{
+        cancelled: "cancelled";
+        timeout: "timeout";
+        "exhausted-retries": "exhausted-retries";
+        "worker-crash": "worker-crash";
+        "execution-error": "execution-error";
+    }>;
+    count: z.ZodNumber;
+    percentage: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Error analysis for a specific workflow or step
+ */
+export declare const errorAnalysisSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+    totalFailures: z.ZodNumber;
+    uniqueErrors: z.ZodNumber;
+    breakdownByReason: z.ZodArray<z.ZodObject<{
+        failureReason: z.ZodEnum<{
+            cancelled: "cancelled";
+            timeout: "timeout";
+            "exhausted-retries": "exhausted-retries";
+            "worker-crash": "worker-crash";
+            "execution-error": "execution-error";
+        }>;
+        count: z.ZodNumber;
+        percentage: z.ZodNumber;
+    }, z.core.$strip>>;
+    mostCommonErrors: z.ZodArray<z.ZodObject<{
+        message: z.ZodString;
+        count: z.ZodNumber;
+        failureReason: z.ZodString;
+        lastOccurrence: z.ZodNumber;
+        occurrences: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            workflowSlug: z.ZodString;
+            runId: z.ZodString;
+            stepId: z.ZodString;
+            attemptNumber: z.ZodNumber;
+            timestampUs: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    firstFailure: z.ZodOptional<z.ZodNumber>;
+    lastFailure: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Retry analysis
+ */
+export declare const retryAnalysisSchema: z.ZodObject<{
+    totalRetries: z.ZodNumber;
+    retriesSucceeded: z.ZodNumber;
+    retriesFailed: z.ZodNumber;
+    averageAttemptsBeforeSuccess: z.ZodNumber;
+    averageAttemptsBeforeFailure: z.ZodNumber;
+    retryEffectivenessRate: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Scheduling latency metrics (time from scheduled to started)
+ */
+export declare const schedulingLatencySchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+    count: z.ZodNumber;
+    averageUs: z.ZodNumber;
+    medianUs: z.ZodNumber;
+    p95Us: z.ZodNumber;
+    p99Us: z.ZodNumber;
+    minUs: z.ZodNumber;
+    maxUs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Step duration metrics
+ */
+export declare const stepDurationSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+    count: z.ZodNumber;
+    averageUs: z.ZodNumber;
+    medianUs: z.ZodNumber;
+    p95Us: z.ZodNumber;
+    p99Us: z.ZodNumber;
+    minUs: z.ZodNumber;
+    maxUs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Workflow duration metrics (end-to-end time)
+ */
+export declare const workflowDurationSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    count: z.ZodNumber;
+    averageUs: z.ZodNumber;
+    medianUs: z.ZodNumber;
+    p95Us: z.ZodNumber;
+    p99Us: z.ZodNumber;
+    minUs: z.ZodNumber;
+    maxUs: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Worker stability metrics
+ */
+export declare const workerStabilitySchema: z.ZodObject<{
+    totalReclamations: z.ZodNumber;
+    uniqueWorkersWithReclamations: z.ZodNumber;
+    stepsReclaimedByWorker: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    averageStaleTimeUs: z.ZodNumber;
+    mostUnstableWorkers: z.ZodArray<z.ZodObject<{
+        workerId: z.ZodString;
+        reclamationCount: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Throughput metrics
+ */
+export declare const throughputSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    timeRangeUs: z.ZodNumber;
+    runsCompleted: z.ZodNumber;
+    runsFailed: z.ZodNumber;
+    stepsCompleted: z.ZodNumber;
+    stepsFailed: z.ZodNumber;
+    stepsSkipped: z.ZodNumber;
+    runsPerHour: z.ZodNumber;
+    stepsPerHour: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Queue depth metrics (current state)
+ */
+export declare const queueDepthSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    pendingRuns: z.ZodNumber;
+    runningRuns: z.ZodNumber;
+    scheduledSteps: z.ZodNumber;
+    runningSteps: z.ZodNumber;
+    oldestScheduledStepUs: z.ZodOptional<z.ZodNumber>;
+    oldestPendingRunUs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Per-workflow queue depth breakdown
+ */
+export declare const queueDepthByWorkflowSchema: z.ZodArray<z.ZodObject<{
+    workflowSlug: z.ZodString;
+    workflowName: z.ZodOptional<z.ZodString>;
+    pendingRuns: z.ZodNumber;
+    scheduledSteps: z.ZodNumber;
+    oldestPendingItemUs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+/**
+ * Success/failure rate metrics
+ */
+export declare const successRateSchema: z.ZodObject<{
+    workflowSlug: z.ZodOptional<z.ZodString>;
+    stepId: z.ZodOptional<z.ZodString>;
+    totalRuns: z.ZodNumber;
+    successfulRuns: z.ZodNumber;
+    failedRuns: z.ZodNumber;
+    cancelledRuns: z.ZodNumber;
+    successRate: z.ZodNumber;
+    failureRate: z.ZodNumber;
+    totalSteps: z.ZodNumber;
+    successfulSteps: z.ZodNumber;
+    failedSteps: z.ZodNumber;
+    skippedSteps: z.ZodNumber;
+    stepSuccessRate: z.ZodNumber;
+    stepFailureRate: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Complete analytics summary
+ */
+export declare const analyticsSummarySchema: z.ZodObject<{
+    timeRange: z.ZodObject<{
+        startUs: z.ZodNumber;
+        endUs: z.ZodNumber;
+        durationUs: z.ZodNumber;
+    }, z.core.$strip>;
+    errorAnalysis: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodString>;
+        totalFailures: z.ZodNumber;
+        uniqueErrors: z.ZodNumber;
+        breakdownByReason: z.ZodArray<z.ZodObject<{
+            failureReason: z.ZodEnum<{
+                cancelled: "cancelled";
+                timeout: "timeout";
+                "exhausted-retries": "exhausted-retries";
+                "worker-crash": "worker-crash";
+                "execution-error": "execution-error";
+            }>;
+            count: z.ZodNumber;
+            percentage: z.ZodNumber;
+        }, z.core.$strip>>;
+        mostCommonErrors: z.ZodArray<z.ZodObject<{
+            message: z.ZodString;
+            count: z.ZodNumber;
+            failureReason: z.ZodString;
+            lastOccurrence: z.ZodNumber;
+            occurrences: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                workflowSlug: z.ZodString;
+                runId: z.ZodString;
+                stepId: z.ZodString;
+                attemptNumber: z.ZodNumber;
+                timestampUs: z.ZodNumber;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        firstFailure: z.ZodOptional<z.ZodNumber>;
+        lastFailure: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    retryAnalysis: z.ZodObject<{
+        totalRetries: z.ZodNumber;
+        retriesSucceeded: z.ZodNumber;
+        retriesFailed: z.ZodNumber;
+        averageAttemptsBeforeSuccess: z.ZodNumber;
+        averageAttemptsBeforeFailure: z.ZodNumber;
+        retryEffectivenessRate: z.ZodNumber;
+    }, z.core.$strip>;
+    schedulingLatency: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodString>;
+        count: z.ZodNumber;
+        averageUs: z.ZodNumber;
+        medianUs: z.ZodNumber;
+        p95Us: z.ZodNumber;
+        p99Us: z.ZodNumber;
+        minUs: z.ZodNumber;
+        maxUs: z.ZodNumber;
+    }, z.core.$strip>;
+    stepDuration: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodString>;
+        count: z.ZodNumber;
+        averageUs: z.ZodNumber;
+        medianUs: z.ZodNumber;
+        p95Us: z.ZodNumber;
+        p99Us: z.ZodNumber;
+        minUs: z.ZodNumber;
+        maxUs: z.ZodNumber;
+    }, z.core.$strip>;
+    workflowDuration: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        count: z.ZodNumber;
+        averageUs: z.ZodNumber;
+        medianUs: z.ZodNumber;
+        p95Us: z.ZodNumber;
+        p99Us: z.ZodNumber;
+        minUs: z.ZodNumber;
+        maxUs: z.ZodNumber;
+    }, z.core.$strip>;
+    workerStability: z.ZodObject<{
+        totalReclamations: z.ZodNumber;
+        uniqueWorkersWithReclamations: z.ZodNumber;
+        stepsReclaimedByWorker: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        averageStaleTimeUs: z.ZodNumber;
+        mostUnstableWorkers: z.ZodArray<z.ZodObject<{
+            workerId: z.ZodString;
+            reclamationCount: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    throughput: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        timeRangeUs: z.ZodNumber;
+        runsCompleted: z.ZodNumber;
+        runsFailed: z.ZodNumber;
+        stepsCompleted: z.ZodNumber;
+        stepsFailed: z.ZodNumber;
+        stepsSkipped: z.ZodNumber;
+        runsPerHour: z.ZodNumber;
+        stepsPerHour: z.ZodNumber;
+    }, z.core.$strip>;
+    queueDepth: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        pendingRuns: z.ZodNumber;
+        runningRuns: z.ZodNumber;
+        scheduledSteps: z.ZodNumber;
+        runningSteps: z.ZodNumber;
+        oldestScheduledStepUs: z.ZodOptional<z.ZodNumber>;
+        oldestPendingRunUs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    successRate: z.ZodObject<{
+        workflowSlug: z.ZodOptional<z.ZodString>;
+        stepId: z.ZodOptional<z.ZodString>;
+        totalRuns: z.ZodNumber;
+        successfulRuns: z.ZodNumber;
+        failedRuns: z.ZodNumber;
+        cancelledRuns: z.ZodNumber;
+        successRate: z.ZodNumber;
+        failureRate: z.ZodNumber;
+        totalSteps: z.ZodNumber;
+        successfulSteps: z.ZodNumber;
+        failedSteps: z.ZodNumber;
+        skippedSteps: z.ZodNumber;
+        stepSuccessRate: z.ZodNumber;
+        stepFailureRate: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type ErrorBreakdown = z.infer<typeof errorBreakdownSchema>;
+export type ErrorAnalysis = z.infer<typeof errorAnalysisSchema>;
+export type RetryAnalysis = z.infer<typeof retryAnalysisSchema>;
+export type SchedulingLatency = z.infer<typeof schedulingLatencySchema>;
+export type StepDuration = z.infer<typeof stepDurationSchema>;
+export type WorkflowDuration = z.infer<typeof workflowDurationSchema>;
+export type WorkerStability = z.infer<typeof workerStabilitySchema>;
+export type Throughput = z.infer<typeof throughputSchema>;
+export type QueueDepth = z.infer<typeof queueDepthSchema>;
+export type QueueDepthByWorkflow = z.infer<typeof queueDepthByWorkflowSchema>;
+export type SuccessRate = z.infer<typeof successRateSchema>;
+export type AnalyticsSummary = z.infer<typeof analyticsSummarySchema>;
+/**
+ * Common options for analytics queries
+ */
+export interface AnalyticsOptions {
+    /**
+     * Start of time range (microseconds since epoch)
+     * Defaults to 24 hours ago
+     */
+    startUs?: number;
+    /**
+     * End of time range (microseconds since epoch)
+     * Defaults to now
+     */
+    endUs?: number;
+    /**
+     * Filter by workflow slug
+     */
+    workflowSlug?: string;
+    /**
+     * Filter by step ID
+     */
+    stepId?: string;
+    /**
+     * Filter by run IDs
+     */
+    runIds?: string[];
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;iBAU/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyB9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;iBAO9B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;iBAUlC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;iBAU7B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;iBASjC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;iBAWhC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAU3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;iBAQ3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;;kBAQtC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;iBAe5B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAejC,CAAC;AAMH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAMtE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB"}

package/dist/error-fingerprint.d.ts

@@ -0,0 +1,43 @@
+import type { StepError } from './schemas.ts';
+export interface ErrorFingerprints {
+    nameHash: string;
+    messageHash: string;
+    stackExactHash: string;
+    stackNormalizedHash: string;
+    stackPortableHash: string;
+}
+/**
+ * Compute all error fingerprint hashes for flexible grouping
+ */
+export declare function computeErrorFingerprints(error: StepError, stack?: string): ErrorFingerprints;
+/**
+ * Extract the top N frames from a stack trace
+ */
+export declare function extractTopFrames(stack: string, count: number): string;
+/**
+ * Remove line and column numbers from stack trace
+ * Example: "at foo (/path/file.js:123:45)" -> "at foo (/path/file.js)"
+ */
+export declare function removeLineNumbers(stack: string): string;
+/**
+ * Normalize file paths in stack trace (remove absolute paths, keep relative)
+ * Example: "at foo (/Users/me/project/src/file.js:10:5)" -> "at foo (src/file.js:10:5)"
+ */
+export declare function normalizePaths(stack: string): string;
+/**
+ * Create SHA-1 hash of input string
+ */
+export declare function hashString(input: string): string;
+/**
+ * Compose a fingerprint from individual hash components
+ */
+export declare function composeFingerprint(fingerprints: ErrorFingerprints, strategy: 'exact' | 'normalized' | 'portable'): string;
+/**
+ * Parse a composite fingerprint back into components
+ */
+export declare function parseFingerprint(fingerprint: string): {
+    nameHash: string;
+    messageHash: string;
+    stackHash: string;
+};
+//# sourceMappingURL=error-fingerprint.d.ts.map

package/dist/error-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-fingerprint.d.ts","sourceRoot":"","sources":["../src/error-fingerprint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,iBAAiB,CAiBnB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAerE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,iBAAiB,EAC/B,QAAQ,EAAE,OAAO,GAAG,YAAY,GAAG,UAAU,GAC5C,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAWA"}