@lssm/lib.contracts-spec 17.3.2

package/dist/visualizations/types.d.ts

@@ -0,0 +1,187 @@
+import type { DocBlock } from '../docs/types.js';
+import type { EventRef, OpRef, PresentationRef } from '../features/index.js';
+import type { OwnerShipMeta } from '../ownership.js';
+export type VisualizationKind = 'metric' | 'cartesian' | 'pie' | 'heatmap' | 'funnel' | 'geo' | 'graph' | 'timeline';
+export type VisualizationCartesianVariant = 'line' | 'bar' | 'area' | 'scatter';
+export type VisualizationGeoVariant = 'scatter' | 'heatmap' | 'map';
+export type VisualizationGeoMode = 'chart' | 'slippy-map';
+export type VisualizationValueFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'dateTime' | 'boolean' | 'duration';
+export interface VisualizationMeta extends OwnerShipMeta {
+    goal: string;
+    context: string;
+    entity?: string;
+}
+export interface VisualizationSource {
+    primary: OpRef;
+    item?: OpRef;
+    mutations?: {
+        create?: OpRef;
+        update?: OpRef;
+        delete?: OpRef;
+    };
+    refreshEvents?: EventRef[];
+    resultPath?: string;
+}
+export interface VisualizationDimension {
+    key: string;
+    label: string;
+    dataPath: string;
+    type?: 'category' | 'number' | 'time' | 'geo' | 'latitude' | 'longitude';
+    description?: string;
+    format?: VisualizationValueFormat;
+}
+export interface VisualizationMeasure {
+    key: string;
+    label: string;
+    dataPath: string;
+    description?: string;
+    format?: VisualizationValueFormat;
+    color?: string;
+    aggregate?: 'sum' | 'avg' | 'count' | 'min' | 'max' | 'last';
+}
+export interface VisualizationSeries {
+    key: string;
+    label: string;
+    measure: string;
+    type?: VisualizationCartesianVariant;
+    color?: string;
+    stack?: string;
+    smooth?: boolean;
+}
+export interface VisualizationThreshold {
+    key: string;
+    value: number;
+    label?: string;
+    operator?: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+    color?: string;
+}
+export interface VisualizationAnnotation {
+    key: string;
+    label: string;
+    kind: 'line' | 'point' | 'band';
+    xDataPath?: string;
+    yDataPath?: string;
+    startDataPath?: string;
+    endDataPath?: string;
+    color?: string;
+}
+export interface VisualizationDrilldownMapping {
+    from: string;
+    to: string;
+}
+export interface VisualizationDrilldown {
+    kind: 'navigation' | 'operation' | 'presentation' | 'data-view';
+    targetKey: string;
+    version?: string;
+    mappings?: VisualizationDrilldownMapping[];
+}
+export interface VisualizationBaseConfig {
+    kind: VisualizationKind;
+    title?: string;
+    description?: string;
+    dimensions?: VisualizationDimension[];
+    measures?: VisualizationMeasure[];
+    series?: VisualizationSeries[];
+    palette?: string[];
+    legend?: boolean;
+    tooltip?: boolean;
+    annotations?: VisualizationAnnotation[];
+    thresholds?: VisualizationThreshold[];
+    drilldown?: VisualizationDrilldown;
+    table?: {
+        caption?: string;
+    };
+}
+export interface MetricVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'metric';
+    measure: string;
+    comparisonMeasure?: string;
+    sparkline?: {
+        dimension: string;
+        measure?: string;
+    };
+}
+export interface CartesianVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'cartesian';
+    variant: VisualizationCartesianVariant;
+    xDimension: string;
+    yMeasures?: string[];
+}
+export interface PieVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'pie';
+    nameDimension: string;
+    valueMeasure: string;
+    donut?: boolean;
+    rose?: boolean;
+}
+export interface HeatmapVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'heatmap';
+    xDimension: string;
+    yDimension: string;
+    valueMeasure: string;
+}
+export interface FunnelVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'funnel';
+    nameDimension: string;
+    valueMeasure: string;
+    sort?: 'ascending' | 'descending' | 'none';
+}
+export type VisualizationGeoJsonSource = {
+    type: 'inline';
+    data: unknown;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'ref';
+    ref: string;
+};
+export interface GeoVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'geo';
+    variant?: VisualizationGeoVariant;
+    mode?: VisualizationGeoMode;
+    nameDimension?: string;
+    longitudeDimension?: string;
+    latitudeDimension?: string;
+    valueMeasure?: string;
+    geoJson?: VisualizationGeoJsonSource;
+}
+/**
+ * Graph visualization configuration.
+ *
+ * Aggregated view of a graph: node counts grouped by a dimension,
+ * edge weights measured across a value measure.
+ */
+export interface GraphVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'graph';
+    /** Dimension key used to group/color nodes (e.g. type, status). */
+    nodeDimension?: string;
+    /** Measure key representing edge weight or count. */
+    edgeWeightMeasure?: string;
+    /** Default layout algorithm for rendering. */
+    layout?: 'force' | 'dag' | 'radial' | 'grid';
+}
+/**
+ * Timeline visualization configuration.
+ *
+ * Projects events or records along a time axis with optional
+ * measure series for density or value overlays.
+ */
+export interface TimelineVisualizationConfig extends VisualizationBaseConfig {
+    kind: 'timeline';
+    /** Dimension key holding the time value (ISO 8601 string or epoch ms). */
+    timeDimension: string;
+    /** Optional dimension key for grouping lanes / swim-lanes. */
+    laneDimension?: string;
+    /** Measure series to render as overlaid charts on the timeline axis. */
+    measureSeries?: string[];
+    /** Optional end-time dimension key for interval/span events. */
+    endDimension?: string;
+}
+export type VisualizationConfig = MetricVisualizationConfig | CartesianVisualizationConfig | PieVisualizationConfig | HeatmapVisualizationConfig | FunnelVisualizationConfig | GeoVisualizationConfig | GraphVisualizationConfig | TimelineVisualizationConfig;
+export declare const tech_contracts_visualizations_graph_DocBlocks: DocBlock[];
+export interface VisualizationStates {
+    empty?: PresentationRef;
+    error?: PresentationRef;
+    loading?: PresentationRef;
+}

package/dist/visualizations/types.js

@@ -0,0 +1 @@
+export const tech_contracts_visualizations_graph_DocBlocks=[{id:"docs.tech.contracts.visualizations.graph",title:"Graph & Timeline Visualization Configs",summary:"`GraphVisualizationConfig` and `TimelineVisualizationConfig` extend `VisualizationKind` with `graph` and `timeline` variants for aggregated graph analytics (node-count by dimension, edge-weight measure) and time-axis projections (time dimension + measure series).",kind:"reference",visibility:"public",route:"/docs/tech/contracts/visualizations/graph",tags:["tech","contracts","visualizations","graph","timeline"],body:"# Graph & Timeline Visualization Configs\n\n## GraphVisualizationConfig (`kind: 'graph'`)\n\nAggregated graph analytics view. Use when you want to visualize node\npopulations grouped by a dimension, or edge weights as a measure \u2014 not\ninteractive graph topology (use `DataViewGraphSpec` for that).\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `nodeDimension` | `string?` | Dimension key to group/color nodes (e.g. type, status). |\n| `edgeWeightMeasure` | `string?` | Measure key representing edge weight or count. |\n| `layout` | `'force' | 'dag' | 'radial' | 'grid'?` | Default layout algorithm. |\n\n## TimelineVisualizationConfig (`kind: 'timeline'`)\n\nProjects records along a time axis. Use for event/activity charts where the\ngoal is aggregate density or value over time \u2014 not interactive graph topology.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `timeDimension` | `string` | **Required.** Dimension key holding the time value. |\n| `laneDimension` | `string?` | Dimension key for grouping swim-lanes. |\n| `measureSeries` | `string[]?` | Measure keys to render as overlaid chart series. |\n| `endDimension` | `string?` | End-time dimension for span/interval events. |\n\n## Choosing Between VisualizationSpec and DataViewGraphSpec\n\n- Use `VisualizationSpec` with `kind: 'graph' | 'timeline'` for **aggregated\n  analytics** (e.g., charts, dashboards).\n- Use `DataViewGraphSpec` with `view.kind: 'graph' | 'timeline-graph'` for\n  **interactive graph topology** (clickable nodes, editable edges, layout\n  algorithms, node inspector panels).\n"}];

package/dist/workflow/adapters/db-adapter.d.ts

@@ -0,0 +1,43 @@
+import type { StateStore, WorkflowState, WorkflowStateFilters } from '../state.js';
+interface WorkflowStateRecord {
+    id: string;
+    name: string;
+    version: string;
+    status: string;
+    currentStep: string;
+    data: unknown;
+    history: unknown[];
+    retryCounts: Record<string, number>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface PrismaClientLike {
+    workflowState: {
+        create: (args: {
+            data: Record<string, unknown>;
+        }) => Promise<WorkflowStateRecord>;
+        findUnique: (args: {
+            where: {
+                id: string;
+            };
+        }) => Promise<WorkflowStateRecord | null>;
+        update: (args: {
+            where: {
+                id: string;
+            };
+            data: Record<string, unknown>;
+        }) => Promise<WorkflowStateRecord>;
+        findMany: (args: {
+            where?: Record<string, unknown>;
+        }) => Promise<WorkflowStateRecord[]>;
+    };
+}
+export declare class PrismaStateStore implements StateStore {
+    private readonly prisma;
+    constructor(prisma: PrismaClientLike);
+    create(state: WorkflowState): Promise<void>;
+    get(workflowId: string): Promise<WorkflowState | undefined>;
+    update(workflowId: string, updater: (current: WorkflowState) => WorkflowState): Promise<WorkflowState>;
+    list(filters?: WorkflowStateFilters): Promise<WorkflowState[]>;
+}
+export {};

package/dist/workflow/adapters/db-adapter.js

@@ -0,0 +1 @@
+export class PrismaStateStore{prisma;constructor(t){this.prisma=t}async create(t){await this.prisma.workflowState.create({data:{id:t.workflowId,name:t.workflowName,version:t.workflowVersion,status:t.status,currentStep:t.currentStep,data:t.data,history:t.history,retryCounts:t.retryCounts??{},createdAt:t.createdAt,updatedAt:t.updatedAt}})}async get(t){const e=await this.prisma.workflowState.findUnique({where:{id:t}});if(!e)return;return{workflowId:e.id,workflowName:e.name,workflowVersion:e.version,currentStep:e.currentStep,data:e.data,history:e.history,retryCounts:e.retryCounts,status:e.status,createdAt:e.createdAt,updatedAt:e.updatedAt}}async update(t,e){const a=await this.get(t);if(!a)throw Error(`Workflow ${t} not found`);const r=e(a),o=await this.prisma.workflowState.update({where:{id:t},data:{status:r.status,currentStep:r.currentStep,data:r.data,history:r.history,retryCounts:r.retryCounts,updatedAt:r.updatedAt}});return{workflowId:o.id,workflowName:o.name,workflowVersion:o.version,currentStep:o.currentStep,data:o.data,history:o.history,retryCounts:o.retryCounts,status:o.status,createdAt:o.createdAt,updatedAt:o.updatedAt}}async list(t){const e={};if(t?.status)e.status=t.status;return(await this.prisma.workflowState.findMany({where:e})).map((r)=>({workflowId:r.id,workflowName:r.name,workflowVersion:r.version,currentStep:r.currentStep,data:r.data,history:r.history,retryCounts:r.retryCounts,status:r.status,createdAt:r.createdAt,updatedAt:r.updatedAt}))}}

package/dist/workflow/adapters/file-adapter.d.ts

@@ -0,0 +1,10 @@
+import type { StateStore } from '../state.js';
+export interface FileStateStoreOptions {
+    /** Absolute or relative path to the persistence file. */
+    filePath: string;
+}
+/**
+ * Placeholder for a file-backed state store adapter.
+ * Implementations should manage locking/concurrency and JSON serialization.
+ */
+export declare function createFileStateStore(_options: FileStateStoreOptions): StateStore;

package/dist/workflow/adapters/file-adapter.js

@@ -0,0 +1 @@
+export function createFileStateStore(t){throw Error("File-backed state store adapter not implemented. Provide a custom adapter that satisfies StateStore.")}

package/dist/workflow/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export * from './db-adapter.js';
+export * from './file-adapter.js';
+export * from './memory-store.js';

package/dist/workflow/adapters/index.js

@@ -0,0 +1 @@
+export*from"./db-adapter.js";export*from"./file-adapter.js";export*from"./memory-store.js";

package/dist/workflow/adapters/memory-store.d.ts

@@ -0,0 +1,13 @@
+import type { StateStore, WorkflowState, WorkflowStateFilters } from '../state.js';
+/**
+ * Naive in-memory state store. Suitable for tests and single-node development
+ * environments. Swap with a database-backed adapter in production.
+ */
+export declare class InMemoryStateStore implements StateStore {
+    private readonly items;
+    create(state: WorkflowState): Promise<void>;
+    get(workflowId: string): Promise<WorkflowState | undefined>;
+    update(workflowId: string, updater: (current: WorkflowState) => WorkflowState): Promise<WorkflowState>;
+    list(filters?: WorkflowStateFilters): Promise<WorkflowState[]>;
+    clear(): void;
+}

package/dist/workflow/adapters/memory-store.js

@@ -0,0 +1 @@
+export class InMemoryStateStore{items=new Map;async create(t){if(this.items.has(t.workflowId))throw Error(`Workflow state already exists: ${t.workflowId}`);this.items.set(t.workflowId,o(t))}async get(t){const e=this.items.get(t);return e?o(e):void 0}async update(t,e){const s=this.items.get(t);if(!s)throw Error(`Workflow state not found for ${t}`);const r=o(e(o(s)));this.items.set(t,r);return o(r)}async list(t){const e=[...this.items.values()];return((t?.status)?e.filter((r)=>r.status===t.status):e).map(o)}clear(){this.items.clear()}}function o(t){return{...t,data:n(t.data),history:t.history.map((e)=>({...e,input:n(e.input),output:n(e.output),startedAt:new Date(e.startedAt),completedAt:e.completedAt?new Date(e.completedAt):void 0})),createdAt:new Date(t.createdAt),updatedAt:new Date(t.updatedAt)}}function n(t){if(t instanceof Date)return new Date(t.getTime());if(Array.isArray(t))return t.map((e)=>n(e));if(t&&typeof t==="object"){const e={};for(const[s,r]of Object.entries(t))e[s]=n(r);return e}return t}

package/dist/workflow/context.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Runtime workflow context for simplified workflow interaction.
+ *
+ * Provides a context object that wraps workflow execution state and
+ * provides convenient methods for state management, transitions,
+ * SLA tracking, and compensation.
+ *
+ * @module workflow/context
+ *
+ * @example
+ * ```typescript
+ * import { createWorkflowContext, WorkflowRunner } from '@lssm/lib.contracts-spec';
+ *
+ * // Create context from running workflow
+ * const ctx = createWorkflowContext(runner, workflowId);
+ *
+ * // Access state
+ * console.log(ctx.currentStep);
+ * console.log(ctx.state.data);
+ *
+ * // Check transitions
+ * if (ctx.canTransition('review')) {
+ *   await ctx.transition('review', { approved: true });
+ * }
+ *
+ * // Track SLA
+ * if (ctx.isSlaViolated('totalDuration')) {
+ *   console.log('Remaining time:', ctx.getRemainingTime('totalDuration'));
+ * }
+ * ```
+ */
+import type { Step, WorkflowSpec } from './spec.js';
+import type { StepExecution, WorkflowState } from './state.js';
+/**
+ * Error thrown when a workflow operation fails.
+ */
+export declare class WorkflowContextError extends Error {
+    readonly errorType: WorkflowContextErrorType;
+    readonly workflowId: string;
+    readonly details?: Record<string, unknown>;
+    constructor(type: WorkflowContextErrorType, workflowId: string, message: string, details?: Record<string, unknown>);
+}
+export type WorkflowContextErrorType = 'invalid_transition' | 'workflow_completed' | 'workflow_failed' | 'step_not_found' | 'guard_rejected' | 'sla_violated';
+export interface WorkflowTransitionResult {
+    success: boolean;
+    previousStep: string;
+    currentStep: string;
+    status: WorkflowState['status'];
+    error?: string;
+}
+export interface AvailableTransition {
+    from: string;
+    to: string;
+    label?: string;
+    condition?: string;
+}
+export interface SlaStatus {
+    key: string;
+    type: 'workflow' | 'step';
+    stepId?: string;
+    limitMs: number;
+    elapsedMs: number;
+    remainingMs: number;
+    violated: boolean;
+    percentUsed: number;
+}
+export interface WorkflowEvent {
+    timestamp: Date;
+    type: 'step_started' | 'step_completed' | 'step_failed' | 'step_retried' | 'transition';
+    stepId?: string;
+    fromStep?: string;
+    toStep?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Runtime context for interacting with a workflow instance.
+ *
+ * Provides a simplified interface over WorkflowRunner for common
+ * workflow operations like state access, transitions, and SLA tracking.
+ */
+export interface WorkflowContext<TData extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique workflow instance identifier. */
+    readonly workflowId: string;
+    /** Workflow spec key. */
+    readonly workflowKey: string;
+    /** Workflow spec version. */
+    readonly workflowVersion: string;
+    /** Current step identifier. */
+    readonly currentStep: string;
+    /** Current workflow status. */
+    readonly status: WorkflowState['status'];
+    /** Workflow data/state. */
+    readonly data: TData;
+    /** Execution history. */
+    readonly history: readonly StepExecution[];
+    /**
+     * Get the current workflow state.
+     * @returns Full workflow state object
+     */
+    getState(): WorkflowState<TData>;
+    /**
+     * Get a value from workflow data.
+     * @param key - Data key to retrieve
+     * @returns Value or undefined
+     */
+    getData<Key extends keyof TData>(key: Key): TData[Key] | undefined;
+    /**
+     * Check if workflow is in a terminal state.
+     * @returns True if completed, failed, or cancelled
+     */
+    isTerminal(): boolean;
+    /**
+     * Check if workflow is running.
+     * @returns True if status is 'running'
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current step definition.
+     * @returns Step definition or undefined
+     */
+    getCurrentStepDef(): Step | undefined;
+    /**
+     * Get the retry count for a step.
+     * @param stepId - Step to check (defaults to current step)
+     * @returns Number of retry attempts
+     */
+    getRetryCount(stepId?: string): number;
+    /**
+     * Check if a transition to a target step is valid.
+     * @param toStepId - Target step identifier
+     * @returns True if transition is valid from current step
+     */
+    canTransition(toStepId: string): boolean;
+    /**
+     * Get all available transitions from current step.
+     * @returns Array of available transitions
+     */
+    getAvailableTransitions(): AvailableTransition[];
+    /**
+     * Check if the current step has any outgoing transitions.
+     * @returns True if there are outgoing transitions
+     */
+    hasNextStep(): boolean;
+    /**
+     * Get remaining time for an SLA constraint.
+     * @param slaKey - 'totalDuration' or step ID
+     * @returns Remaining milliseconds, or null if no SLA configured
+     */
+    getRemainingTime(slaKey: string): number | null;
+    /**
+     * Check if an SLA constraint has been violated.
+     * @param slaKey - 'totalDuration' or step ID
+     * @returns True if SLA has been violated
+     */
+    isSlaViolated(slaKey: string): boolean;
+    /**
+     * Get status of all SLA constraints.
+     * @returns Array of SLA statuses
+     */
+    getAllSlaStatuses(): SlaStatus[];
+    /**
+     * Check if compensation/rollback is available.
+     * @returns True if workflow has compensation strategy
+     */
+    hasCompensation(): boolean;
+    /**
+     * Get steps that have compensation handlers.
+     * @returns Array of step IDs with compensation
+     */
+    getCompensableSteps(): string[];
+    /**
+     * Convert execution history to workflow events.
+     * @returns Array of workflow events
+     */
+    getEvents(): WorkflowEvent[];
+}
+/**
+ * Creates a workflow context from state and spec.
+ *
+ * @param state - Current workflow state
+ * @param spec - Workflow specification
+ * @returns WorkflowContext for interacting with the workflow
+ *
+ * @example
+ * ```typescript
+ * const state = await runner.getState(workflowId);
+ * const spec = registry.get(state.workflowName, state.workflowVersion);
+ * const ctx = createWorkflowContext(state, spec);
+ *
+ * console.log('Current step:', ctx.currentStep);
+ * console.log('Available transitions:', ctx.getAvailableTransitions());
+ * ```
+ */
+export declare function createWorkflowContext<TData extends Record<string, unknown> = Record<string, unknown>>(state: WorkflowState<TData>, spec: WorkflowSpec): WorkflowContext<TData>;
+/**
+ * Calculate workflow progress as a percentage.
+ *
+ * @param ctx - Workflow context
+ * @returns Progress percentage (0-100)
+ */
+export declare function calculateWorkflowProgress(ctx: WorkflowContext): number;
+/**
+ * Get the duration of a workflow in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Duration in milliseconds
+ */
+export declare function getWorkflowDuration(ctx: WorkflowContext): number;
+/**
+ * Get the average step duration in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Average duration or 0 if no completed steps
+ */
+export declare function getAverageStepDuration(ctx: WorkflowContext): number;

package/dist/workflow/context.js

@@ -0,0 +1 @@
+class u{state;spec;constructor(t,e){this.state=t;this.spec=e}get workflowId(){return this.state.workflowId}get workflowKey(){return this.state.workflowName}get workflowVersion(){return this.state.workflowVersion}get currentStep(){return this.state.currentStep}get status(){return this.state.status}get data(){return this.state.data}get history(){return this.state.history}getState(){return this.state}getData(t){return this.state.data[t]}isTerminal(){return this.state.status==="completed"||this.state.status==="failed"||this.state.status==="cancelled"}isRunning(){return this.state.status==="running"}getCurrentStepDef(){return this.spec.definition.steps?.find((t)=>t.id===this.state.currentStep)}getRetryCount(t){const e=t??this.state.currentStep;return this.state.retryCounts?.[e]??0}canTransition(t){return(this.spec.definition.transitions??[]).filter((r)=>r.from===this.state.currentStep&&r.to===t).length>0}getAvailableTransitions(){return(this.spec.definition.transitions??[]).filter((t)=>t.from===this.state.currentStep).map((t)=>({from:t.from,to:t.to,label:t.label,condition:t.condition}))}hasNextStep(){return(this.spec.definition.transitions??[]).some((t)=>t.from===this.state.currentStep)}getRemainingTime(t){const e=this.spec.definition.sla;if(!e)return null;const r=Date.now();if(t==="totalDuration"){if(!e.totalDurationMs)return null;const o=r-this.state.createdAt.getTime();return Math.max(0,e.totalDurationMs-o)}const n=e.stepDurationMs?.[t];if(!n)return null;const s=this.state.history.find((o)=>o.stepId===t&&o.status==="running");if(!s)return n;const i=r-s.startedAt.getTime();return Math.max(0,n-i)}isSlaViolated(t){const e=this.getRemainingTime(t);return e!==null&&e<=0}getAllSlaStatuses(){const t=this.spec.definition.sla;if(!t)return[];const e=[],r=Date.now();if(t.totalDurationMs){const n=r-this.state.createdAt.getTime(),s=Math.max(0,t.totalDurationMs-n);e.push({key:"totalDuration",type:"workflow",limitMs:t.totalDurationMs,elapsedMs:n,remainingMs:s,violated:s<=0,percentUsed:n/t.totalDurationMs*100})}if(t.stepDurationMs)for(const[n,s]of Object.entries(t.stepDurationMs)){const i=this.state.history.find((l)=>l.stepId===n&&l.status==="running"),o=i?r-i.startedAt.getTime():0,a=Math.max(0,s-o);e.push({key:n,type:"step",stepId:n,limitMs:s,elapsedMs:o,remainingMs:a,violated:i!==void 0&&a<=0,percentUsed:o/s*100})}return e}hasCompensation(){return this.spec.definition.compensation!==void 0}getCompensableSteps(){const t=this.spec.definition.compensation;if(!t)return[];return t.steps.map((e)=>e.stepId)}getEvents(){const t=[];for(const e of this.state.history){t.push({timestamp:e.startedAt,type:"step_started",stepId:e.stepId,input:e.input});if(e.completedAt){if(e.status==="completed")t.push({timestamp:e.completedAt,type:"step_completed",stepId:e.stepId,output:e.output});else if(e.status==="failed")t.push({timestamp:e.completedAt,type:"step_failed",stepId:e.stepId,error:e.error})}}t.sort((e,r)=>e.timestamp.getTime()-r.timestamp.getTime());return t}}export class WorkflowContextError extends Error{errorType;workflowId;details;constructor(t,e,r,n){super(r);this.name="WorkflowContextError";this.errorType=t;this.workflowId=e;this.details=n}}export function createWorkflowContext(t,e){return new u(t,e)}export function calculateWorkflowProgress(t){const e=t.getState(),r=new Set(e.history.filter((s)=>s.status==="completed").map((s)=>s.stepId)),n=r.size+(t.isTerminal()?0:1);if(t.status==="completed")return 100;if(t.status==="failed"||t.status==="cancelled")return r.size>0?Math.min(99,r.size*20):0;return Math.min(99,r.size*20)}export function getWorkflowDuration(t){const e=t.getState();return(t.isTerminal()?e.updatedAt.getTime():Date.now())-e.createdAt.getTime()}export function getAverageStepDuration(t){const e=t.history.filter((n)=>n.status==="completed"&&n.completedAt);if(e.length===0)return 0;return e.reduce((n,s)=>{if(!s.completedAt)return n;const i=s.completedAt.getTime()-s.startedAt.getTime();return n+i},0)/e.length}

package/dist/workflow/dag-utils.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowDefinition, WorkflowEdge } from './spec.js';
+/**
+ * Detect whether a workflow definition uses the V2 DAG shape (`tasks[]` +
+ * `edges[]`) or the V1 step/transition shape.
+ *
+ * V2 takes precedence when `tasks` is a non-empty array.
+ */
+export declare function detectShape(def: WorkflowDefinition): 'v1' | 'v2';
+/**
+ * Topological sort (Kahn's algorithm) for a V2 DAG task list.
+ *
+ * @param taskIds - All task IDs in the DAG.
+ * @param edges   - Directed edges `{ from, to }` where `from` must complete
+ *                  before `to` can start.
+ * @returns Task IDs in a valid execution order (dependencies before dependents).
+ * @throws If a cycle is detected (should not occur on valid workflows).
+ */
+export declare function topoSortTasks(taskIds: string[], edges: WorkflowEdge[]): string[];

package/dist/workflow/dag-utils.js

@@ -0,0 +1 @@
+export function detectShape(e){return Array.isArray(e.tasks)&&e.tasks.length>0?"v2":"v1"}export function topoSortTasks(e,f){const o=new Map(e.map((t)=>[t,0])),i=new Map(e.map((t)=>[t,[]]));for(const t of f){i.get(t.from)?.push(t.to);o.set(t.to,(o.get(t.to)??0)+1)}const r=[];for(const[t,n]of o)if(n===0)r.push(t);const s=[];while(r.length>0){const t=r.shift();s.push(t);for(const n of i.get(t)??[]){const g=(o.get(n)??1)-1;o.set(n,g);if(g===0)r.push(n)}}if(s.length!==e.length)throw Error(`[workflow/dag-utils] Cycle detected in task graph. Sorted ${s.length} of ${e.length} tasks.`);return s}

package/dist/workflow/expression.d.ts

@@ -0,0 +1,6 @@
+export interface ExpressionContext {
+    data: Record<string, unknown>;
+    input?: unknown;
+    output?: unknown;
+}
+export declare function evaluateExpression(expression: string | undefined, ctx: ExpressionContext): boolean;

package/dist/workflow/expression.js

@@ -0,0 +1 @@
+export function evaluateExpression(t,n){if(!t)return!0;const e=t.trim();if(!e)return!0;const r=l(e,"||");if(r.length>1)return r.some((i)=>evaluateExpression(i,n));const u=l(e,"&&");if(u.length>1)return u.every((i)=>evaluateExpression(i,n));return m(e,n)}function m(t,n){const e=t.trim();if(!e)return!0;if(e.startsWith("!"))return!m(e.slice(1),n);const r=e.match(/^(data|input|output)\.([A-Za-z0-9_.[\]]+)\s*(===|==|!==|!=|>=|<=|>|<)\s*(.+)$/);if(r){const[,s,o,a,p]=r,d=f(s,n,o),g=c(p);return h(d,g,a)}const u=e.match(/^(data|input|output)\.([A-Za-z0-9_.[\]]+)$/);if(u){const[,s,o]=u,a=f(s,n,o);return Boolean(a)}const i=c(e);return Boolean(i)}function h(t,n,e){switch(e){case"===":case"==":return t===n;case"!==":case"!=":return t!==n;case">":return Number(t)>Number(n);case">=":return Number(t)>=Number(n);case"<":return Number(t)<Number(n);case"<=":return Number(t)<=Number(n);default:return!1}}function c(t){const n=(t??"").trim();if(n.startsWith('"')&&n.endsWith('"')||n.startsWith("'")&&n.endsWith("'"))return n.slice(1,-1);if(/^-?\d+(\.\d+)?$/.test(n))return Number(n);if(/^true$/i.test(n))return!0;if(/^false$/i.test(n))return!1;if(/^null$/i.test(n))return null;if(/^undefined$/i.test(n))return;return n}function f(t,n,e){const r=t==="data"?n.data:t==="input"?n.input:n.output;return b(r,e)}function b(t,n){if(t==null)return;if(!n)return t;const e=n.replace(/\[(\d+)\]/g,".$1").split(".").filter(Boolean);let r=t;for(const u of e){if(r==null)return;r=r[u]}return r}function l(t,n){const e=[];let r="",u=!1,i=!1;for(let s=0;s<t.length;s++){const o=t[s];if(!o)continue;const a=t.slice(s,s+n.length);if(o==="'"&&!i){u=!u;r+=o;continue}if(o==='"'&&!u){i=!i;r+=o;continue}if(!u&&!i&&a===n){e.push(r.trim());r="";s+=n.length-1;continue}r+=o}if(r.trim().length)e.push(r.trim());return e}

package/dist/workflow/index.d.ts

@@ -0,0 +1,10 @@
+export * from './adapters/index.js';
+export * from './context.js';
+export * from './expression.js';
+export * from './runner.js';
+export * from './sla-monitor.js';
+export * from './spec.js';
+export * from './state.js';
+export * from './validation.js';
+export * from './workflow-devkit.js';
+export * from './workflow-sdk.js';

package/dist/workflow/index.js

@@ -0,0 +1 @@
+export*from"./adapters/index.js";export*from"./context.js";export*from"./expression.js";export*from"./runner.js";export*from"./sla-monitor.js";export*from"./spec.js";export*from"./state.js";export*from"./validation.js";export*from"./workflow-devkit.js";export*from"./workflow-sdk.js";

package/dist/workflow/runner.d.ts

@@ -0,0 +1,103 @@
+import type { ResolvedBranding } from '../app-config/branding.js';
+import type { ResolvedAppConfig, ResolvedIntegration, ResolvedKnowledge, ResolvedTranslation } from '../app-config/runtime.js';
+import type { OpRef } from '../features/index.js';
+import type { SecretProviderPort, TranslationResolver } from '../types.js';
+import type { GuardCondition, Step, WorkflowExecutionErrorKind, WorkflowRegistry } from './spec.js';
+import type { StateStore, WorkflowState } from './state.js';
+export interface OperationExecutorContext {
+    workflow: WorkflowState;
+    step?: Step;
+    resolvedAppConfig?: ResolvedAppConfig;
+    integrations?: ResolvedIntegration[];
+    knowledge?: ResolvedKnowledge[];
+    branding?: ResolvedBranding;
+    translation?: ResolvedTranslation;
+    translationResolver?: TranslationResolver;
+    secretProvider?: SecretProviderPort;
+}
+export type OperationExecutor = (op: OpRef, input: unknown, context: OperationExecutorContext) => Promise<unknown>;
+export type WorkflowPreFlightIssueType = 'integration' | 'capability';
+export type WorkflowPreFlightIssueSeverity = 'error' | 'warning';
+export interface WorkflowPreFlightIssue {
+    stepId: string;
+    type: WorkflowPreFlightIssueType;
+    identifier: string;
+    severity: WorkflowPreFlightIssueSeverity;
+    reason: string;
+}
+export interface WorkflowPreFlightResult {
+    canStart: boolean;
+    issues: WorkflowPreFlightIssue[];
+}
+export interface GuardContext {
+    workflow: WorkflowState;
+    step: Step;
+    input?: unknown;
+}
+export type GuardEvaluator = (guard: GuardCondition, context: GuardContext) => Promise<boolean> | boolean;
+export type WorkflowTimerHandle = ReturnType<typeof globalThis.setTimeout>;
+export interface WorkflowTimerPort {
+    setTimeout(callback: () => void, ms?: number): WorkflowTimerHandle;
+    clearTimeout(handle: WorkflowTimerHandle): void;
+}
+export interface WorkflowRunnerConfig {
+    registry: WorkflowRegistry;
+    stateStore: StateStore;
+    opExecutor: OperationExecutor;
+    guardEvaluator?: GuardEvaluator;
+    eventEmitter?: (event: string, payload: Record<string, unknown>) => void;
+    appConfigProvider?: (state: WorkflowState) => ResolvedAppConfig | undefined | Promise<ResolvedAppConfig | undefined>;
+    enforceCapabilities?: (operation: OpRef, context: OperationExecutorContext) => void | Promise<void>;
+    secretProvider?: SecretProviderPort;
+    translationResolver?: TranslationResolver;
+    timers?: WorkflowTimerPort;
+}
+export declare class WorkflowRunner {
+    private readonly config;
+    constructor(config: WorkflowRunnerConfig);
+    private get timers();
+    preFlightCheck(workflowName: string, version?: string, // Update to string
+    resolvedConfig?: ResolvedAppConfig): Promise<WorkflowPreFlightResult>;
+    start(workflowName: string, version?: string, initialData?: Record<string, unknown>): Promise<string>;
+    executeStep(workflowId: string, input?: unknown): Promise<void>;
+    rollback(workflowId: string): Promise<void>;
+    getState(workflowId: string): Promise<WorkflowState>;
+    pause(workflowId: string): Promise<void>;
+    resume(workflowId: string): Promise<void>;
+    cancel(workflowId: string): Promise<void>;
+    /**
+     * Execute a V2 DAG workflow (Path B — full operation parity).
+     *
+     * Algorithm:
+     * 1. Topological sort of `edges[]` using Kahn's algorithm.
+     * 2. Restore persisted task status from `state.data.__v2TaskStatus__` so
+     *    human-task resume picks up where it left off.
+     * 3. For each pending task in topo order:
+     *    a. Cascade-skip when any upstream is skipped.
+     *    b. Edge guards: `runIf` + `condition` — skip if either evaluates false.
+     *    c. Task guard — skip if `guard` evaluates false.
+     *    d. `human` type → suspend: emit `workflow.task_waiting`, save state, return.
+     *    e. `automation` / `decision` → dispatch `operation` via OperationExecutor
+     *       with optional retry (fixed/exponential backoff) and `timeoutMs` cap.
+     * 4. Emit `workflow.step_completed` when all tasks finish.
+     */
+    private executeV2Dag;
+    /**
+     * Evaluate a task-level guard.
+     * `expression` guards use `evaluateExpression()`; `policy` guards delegate to
+     * the configured `guardEvaluator` (fail-open when none is provided).
+     */
+    private evalTaskGuard;
+    private performPreFlight;
+    private getSpec;
+    private getStateOrThrow;
+    private emit;
+}
+export declare class WorkflowPreFlightError extends Error {
+    readonly issues: WorkflowPreFlightIssue[];
+    constructor(issues: WorkflowPreFlightIssue[]);
+}
+export declare class WorkflowExecutionError extends Error {
+    readonly kind: WorkflowExecutionErrorKind;
+    constructor(message: string, kind: WorkflowExecutionErrorKind);
+}