@lssm/lib.contracts-spec 17.3.2

package/dist/workflow/runner.js

@@ -0,0 +1 @@
+export class WorkflowRunner{config;constructor(t){this.config=t}get timers(){return this.config.timers??globalThis}async preFlightCheck(t,e,r){const d=this.getSpec(t,e);return this.performPreFlight(d,r)}async start(t,e,r){const d=this.getSpec(t,e),a=new Date,p=x(),i=x(),o={workflowId:p,traceId:i,workflowName:d.meta.key,workflowVersion:d.meta.version,currentStep:"",data:{...r??{}},retryCounts:{},history:[],status:"running",createdAt:a,updatedAt:a},s=this.config.appConfigProvider?await this.config.appConfigProvider(o):void 0,n=await this.performPreFlight(d,s);if(!n.canStart)throw new WorkflowPreFlightError(n.issues);await this.config.stateStore.create(o);this.emit("workflow.started",{workflowId:p,traceId:i,workflowName:d.meta.key,workflowVersion:d.meta.version});return p}async executeStep(t,e){const r=await this.getStateOrThrow(t);if(O(r.status))throw Error(`Workflow ${t} is in terminal status "${r.status}".`);return this.executeV2Dag(t,e)}async rollback(t){const e=await this.getStateOrThrow(t),r=this.getSpec(e.workflowName,e.workflowVersion);if(!r.definition.compensation)return;this.emit("workflow.rollback_started",{workflowId:t,traceId:e.traceId});const d=e.history.filter((a)=>a.status==="completed").reverse();for(const a of d){const p=r.definition.compensation.steps.find((i)=>i.stepId===a.stepId);if(p){const i={stepId:a.stepId,originalInput:a.input,originalOutput:a.output,workflowData:e.data};try{const o=this.config.appConfigProvider?await this.config.appConfigProvider(e):void 0,s={workflow:e,resolvedAppConfig:o,integrations:o?.integrations??[],knowledge:o?.knowledge??[],branding:o?.branding,translation:o?.translation,translationResolver:this.config.translationResolver,secretProvider:this.config.secretProvider};await this.config.opExecutor(p.operation,i,s);this.emit("workflow.compensation_step_completed",{workflowId:t,traceId:e.traceId,stepId:a.stepId,compensationOp:p.operation.key})}catch(o){const s=o instanceof Error?o.message:String(o);this.emit("workflow.compensation_step_failed",{workflowId:t,traceId:e.traceId,stepId:a.stepId,compensationOp:p.operation.key,error:s})}}}this.emit("workflow.rollback_completed",{workflowId:t,traceId:e.traceId})}async getState(t){return this.getStateOrThrow(t)}async pause(t){const e=await this.getStateOrThrow(t);if(e.status!=="running")return;const r={...e,status:"paused",updatedAt:new Date};await this.config.stateStore.update(t,()=>r);this.emit("workflow.paused",{workflowId:t,traceId:e.traceId,workflowName:e.workflowName})}async resume(t){const e=await this.getStateOrThrow(t);if(e.status!=="paused")return;const r={...e,status:"running",updatedAt:new Date};await this.config.stateStore.update(t,()=>r);this.emit("workflow.resumed",{workflowId:t,traceId:e.traceId,workflowName:e.workflowName})}async cancel(t){const e=await this.getStateOrThrow(t);if(e.status==="cancelled")return;const r={...e,status:"cancelled",updatedAt:new Date};await this.config.stateStore.update(t,()=>r);this.emit("workflow.cancelled",{workflowId:t,traceId:e.traceId,workflowName:e.workflowName})}async executeV2Dag(t,e){const r=await this.getStateOrThrow(t),d=this.getSpec(r.workflowName,r.workflowVersion),a=d.definition.tasks??[],p=d.definition.edges??[],i=R(a.map((l)=>l.id),p),o=r.data.__v2TaskStatus__??{},s=new Map(i.map((l)=>[l,o[l]??"pending"])),n={...r,data:{...r.data},history:[...r.history],status:"running",wait:void 0},f=r.status==="waiting"&&r.wait?.reason==="human_input"?r.currentStep:void 0;if(f){s.set(f,"completed");if(e!==void 0)n.data={...n.data,[`${f}.output`]:e}}for(const l of i){const m=s.get(l);if(m==="completed"||m==="skipped")continue;const u=a.find((c)=>c.id===l);if(!u)continue;const y=p.filter((c)=>c.to===l),v=y.some((c)=>s.get(c.from)==="skipped"),I=!v&&y.some((c)=>c.runIf!==void 0&&!h(c.runIf,{data:n.data})||c.condition!==void 0&&!h(c.condition,{data:n.data}));if(v||I){s.set(l,"skipped");this.emit("workflow.task_skipped_runIf",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label});continue}if(u.guard){if(!await this.evalTaskGuard(u.guard,n,u)){s.set(l,"skipped");this.emit("workflow.task_skipped_runIf",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label});continue}}if(u.type==="human"){n.status="waiting";n.currentStep=l;n.wait={reason:"human_input",stepId:l,requestedAt:new Date};n.data={...n.data,__v2TaskStatus__:Object.fromEntries(s)};n.updatedAt=new Date;await this.config.stateStore.update(t,()=>n);this.emit("workflow.task_waiting",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label});return}this.emit("workflow.task_started",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label});try{if(u.operation){const c=this.config.appConfigProvider?await this.config.appConfigProvider(n):void 0,w={workflow:n,resolvedAppConfig:c,integrations:c?.integrations??[],knowledge:c?.knowledge??[],branding:c?.branding,translation:c?.translation,translationResolver:this.config.translationResolver,secretProvider:this.config.secretProvider},b=()=>this.config.opExecutor(u.operation,n.data,w),S=u.retry?C(b,u.retry,this.timers):b(),P=u.timeoutMs?await _(S,u.timeoutMs,this.timers):await S;if(E(P))n.data={...n.data,...P}}s.set(l,"completed");n.updatedAt=new Date;this.emit("workflow.task_completed",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label})}catch(c){s.set(l,"failed");const w=c instanceof Error?c.message:String(c);n.status="failed";n.data={...n.data,__v2TaskStatus__:Object.fromEntries(s)};n.updatedAt=new Date;await this.config.stateStore.update(t,()=>n);this.emit("workflow.task_failed",{workflowId:t,traceId:r.traceId,taskId:l,taskLabel:u.label,error:w});this.emit("workflow.step_failed",{workflowId:t,traceId:r.traceId,workflowName:r.workflowName,stepId:l,error:w});return}}n.status="completed";n.data={...n.data,__v2TaskStatus__:Object.fromEntries(s)};n.updatedAt=new Date;await this.config.stateStore.update(t,()=>n);this.emit("workflow.step_completed",{workflowId:t,traceId:r.traceId,workflowName:r.workflowName,stepId:"",status:"completed"})}async evalTaskGuard(t,e,r){if(t.type==="expression")return h(t.value,{data:e.data});if(this.config.guardEvaluator){const d={id:r.id,type:r.type??"automation",label:r.label};return this.config.guardEvaluator({type:"policy",value:t.value},{workflow:e,step:d})}return!0}async performPreFlight(t,e){if(!e)return{canStart:!0,issues:[]};const r=[],d=new Map;for(const i of e.integrations)d.set(i.slot.slotId,i);for(const i of t.definition.steps??[])for(const o of i.requiredIntegrations??[]){const s=d.get(o);if(!s){r.push({stepId:i.id,type:"integration",identifier:o,severity:"error",reason:`Integration slot "${o}" is not bound in the resolved app config.`});continue}const n=s.connection.status;if(n==="disconnected"||n==="error")r.push({stepId:i.id,type:"integration",identifier:o,severity:"error",reason:`Integration slot "${o}" is in status "${n}".`});else if(n==="unknown")r.push({stepId:i.id,type:"integration",identifier:o,severity:"warning",reason:`Integration slot "${o}" reports unknown health status.`})}const a=new Set(e.capabilities.enabled.map(g));for(const i of t.definition.steps??[])for(const o of i.requiredCapabilities??[])if(!a.has(g(o)))r.push({stepId:i.id,type:"capability",identifier:g(o),severity:"error",reason:`Capability "${o.key}@${o.version}" is not enabled.`});for(const i of t.definition.tasks??[]){for(const o of i.requiredIntegrations??[]){const s=d.get(o);if(!s){r.push({stepId:i.id,type:"integration",identifier:o,severity:"error",reason:`Integration slot "${o}" is not bound in the resolved app config.`});continue}const n=s.connection.status;if(n==="disconnected"||n==="error")r.push({stepId:i.id,type:"integration",identifier:o,severity:"error",reason:`Integration slot "${o}" is in status "${n}".`});else if(n==="unknown")r.push({stepId:i.id,type:"integration",identifier:o,severity:"warning",reason:`Integration slot "${o}" reports unknown health status.`})}for(const o of i.requiredCapabilities??[])if(!a.has(g(o)))r.push({stepId:i.id,type:"capability",identifier:g(o),severity:"error",reason:`Capability "${o.key}@${o.version}" is not enabled.`})}return{canStart:r.every((i)=>i.severity!=="error"),issues:r}}getSpec(t,e){const r=this.config.registry.get(t,e);if(!r)throw Error(`Workflow spec not found for ${t}${e?`.v${e}`:""}`);return r}async getStateOrThrow(t){const e=await this.config.stateStore.get(t);if(!e)throw Error(`Workflow state not found for ${t}`);return e}emit(t,e){this.config.eventEmitter?.(t,e)}}import{normalizeContractError as W,problemToSafeMessage as k}from"../results/index.js";import{topoSortTasks as R}from"./dag-utils.js";import{evaluateExpression as h}from"./expression.js";function x(){return globalThis.crypto?.randomUUID?.()??`id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,10)}`}function E(t){return t!=null&&typeof t==="object"&&!Array.isArray(t)}async function C(t,e,r=globalThis){const{maxAttempts:d,backoff:a="fixed",delayMs:p=0,maxDelayMs:i}=e;let o;for(let s=1;s<=d;s++)try{return await t()}catch(n){o=n;if(s<d&&p>0){const f=a==="exponential"?p*2**(s-1):p,l=i!==void 0?Math.min(f,i):f;await new Promise((m)=>r.setTimeout(m,l))}}throw o}function _(t,e,r=globalThis){let d;const a=new Promise((p,i)=>{d=r.setTimeout(()=>i(new WorkflowExecutionError(`Task timed out after ${e}ms`,"timeout")),e)});return Promise.race([t,a]).finally(()=>{if(d!==void 0)r.clearTimeout(d)})}function O(t){return t==="completed"||t==="failed"||t==="cancelled"}export class WorkflowPreFlightError extends Error{issues;constructor(t){super(`Workflow pre-flight failed: ${t.filter((e)=>e.severity==="error").map((e)=>`${e.type}:${e.identifier}`).join(", ")}`);this.issues=t;this.name="WorkflowPreFlightError"}}export class WorkflowExecutionError extends Error{kind;constructor(t,e){super(t);this.kind=e;this.name="WorkflowExecutionError"}}function g(t){return`${t.key}@${t.version}`}function M(t){const e=W(t,{source:{service:"workflow"}});if(t instanceof WorkflowExecutionError){const a=T(e.problem,t.kind);return{kind:t.kind,message:k(a),retryable:t.kind==="retryable"||t.kind==="timeout",problem:a}}const r=A(t);if(r){const a=T(e.problem,r);return{kind:r,message:k(a),retryable:r==="retryable"||r==="timeout",problem:a}}return{kind:e.problem.retryable?"retryable":"fatal",message:k(e.problem),retryable:e.problem.retryable,problem:e.problem}}function T(t,e){const r=e==="retryable"||e==="timeout";return{...t,category:e==="policy_blocked"?"policy":e==="guard_rejected"?"workflow":e==="timeout"?"timeout":t.category,retryable:r}}function K(t){if(t instanceof Date)return Math.max(0,t.getTime()-Date.now());if(typeof t==="number")return Math.max(0,t);return}function A(t){if(typeof t!=="object"||t===null||!("kind"in t))return;const e=t.kind;if(e==="fatal"||e==="retryable"||e==="timeout"||e==="guard_rejected"||e==="policy_blocked")return e;return}

package/dist/workflow/sla-monitor.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowSpec } from './spec.js';
+import type { WorkflowState } from './state.js';
+export interface SLABreachEvent {
+    workflowId: string;
+    workflowName: string;
+    type: 'workflow_duration' | 'step_duration';
+    stepId?: string;
+    expectedMs: number;
+    actualMs: number;
+    breachedAt: Date;
+}
+export declare class SLAMonitor {
+    private readonly eventEmitter;
+    constructor(eventEmitter: (event: string, payload: SLABreachEvent) => void);
+    check(state: WorkflowState, spec: WorkflowSpec): void;
+}

package/dist/workflow/sla-monitor.js

@@ -0,0 +1 @@
+export class SLAMonitor{eventEmitter;constructor(t){this.eventEmitter=t}check(t,a){const e=a.definition.sla;if(!e)return;const n=new Date().getTime();if(e.totalDurationMs){const o=n-t.createdAt.getTime();if(o>e.totalDurationMs){if(t.status==="running"||t.status==="paused"||t.status==="waiting")this.eventEmitter("workflow.sla_breach",{workflowId:t.workflowId,workflowName:t.workflowName,type:"workflow_duration",expectedMs:e.totalDurationMs,actualMs:o,breachedAt:new Date})}}if(e.stepDurationMs){if(t.status==="running"&&t.currentStep){const o=t.history.find((r)=>r.stepId===t.currentStep&&r.status==="running");if(o){const r=e.stepDurationMs[t.currentStep];if(r){const i=n-o.startedAt.getTime();if(i>r)this.eventEmitter("workflow.sla_breach",{workflowId:t.workflowId,workflowName:t.workflowName,type:"step_duration",stepId:t.currentStep,expectedMs:r,actualMs:i,breachedAt:new Date})}}}}}}

package/dist/workflow/spec.d.ts

@@ -0,0 +1,203 @@
+import type { CapabilityRef } from '../capabilities/index.js';
+import type { DecisionGraphRef } from '../decisioning/index.js';
+import type { PredicateSpec } from '../decisioning/predicate.js';
+import type { DocBlock } from '../docs/types.js';
+import type { ExperimentRef } from '../experiments/spec.js';
+import type { FormRef, OpRef } from '../features/index.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import { SpecContractRegistry } from '../registry.js';
+import type { ResultCatalog } from '../results/index.js';
+import type { WorkflowRuntimeAdapterKey } from '../runtime-adapters.js';
+import type { SharedTask } from '../shared-entities/task.js';
+import type { WorkflowDevkitRuntimeConfig, WorkflowStepRuntimeConfig } from './workflow-devkit.js';
+export type { WorkflowRuntimeAdapterKey } from '../runtime-adapters.js';
+export type { JsonValue, WorkflowDevkitApprovalWaitStepConfig, WorkflowDevkitHookTokenConfig, WorkflowDevkitHookTokenStrategy, WorkflowDevkitHookWaitStepConfig, WorkflowDevkitHostTarget, WorkflowDevkitIdentityConfig, WorkflowDevkitIntegrationMode, WorkflowDevkitResumeSource, WorkflowDevkitRunIdentityStrategy, WorkflowDevkitRuntimeConfig, WorkflowDevkitSerializationConfig, WorkflowDevkitSerializationMode, WorkflowDevkitSleepStepConfig, WorkflowDevkitStepBehavior, WorkflowDevkitStepRuntimeConfig, WorkflowDevkitStreamSessionStepConfig, WorkflowDevkitWebhookWaitStepConfig, WorkflowStepRuntimeConfig, } from './workflow-devkit.js';
+export type { FormRef };
+export type StepType = 'human' | 'automation' | 'decision';
+export type WorkflowStatus = 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled';
+export type GuardConditionKind = 'policy' | 'expression';
+export type WorkflowExecutionErrorKind = 'fatal' | 'retryable' | 'timeout' | 'guard_rejected' | 'policy_blocked';
+export interface WorkflowRuntimeCapabilities {
+    /** Optional adapter availability map for external workflow runtimes. */
+    adapters?: Partial<Record<WorkflowRuntimeAdapterKey, boolean>>;
+    /** Whether workflow execution should persist checkpoints. */
+    checkpointing?: boolean;
+    /** Whether workflow execution supports suspend/resume semantics. */
+    suspendResume?: boolean;
+    /** Whether workflow execution can delegate to approval gateways. */
+    approvalGateway?: boolean;
+}
+export interface WorkflowRuntimePorts {
+    /** Symbolic identifier for checkpoint store adapter. */
+    checkpointStore?: string;
+    /** Symbolic identifier for suspend/resume adapter. */
+    suspension?: string;
+    /** Symbolic identifier for retry classifier adapter. */
+    retryClassifier?: string;
+    /** Symbolic identifier for approval gateway adapter. */
+    approvalGateway?: string;
+}
+export interface WorkflowRuntimeConfig {
+    capabilities?: WorkflowRuntimeCapabilities;
+    ports?: WorkflowRuntimePorts;
+    workflowDevkit?: WorkflowDevkitRuntimeConfig;
+}
+export interface GuardCondition {
+    type: GuardConditionKind;
+    /** Policy name or expression string depending on the type. */
+    value: string;
+}
+export interface RetryPolicy {
+    maxAttempts: number;
+    backoff: 'linear' | 'exponential';
+    delayMs: number;
+    /** Optional max delay cap for exponential backoff. */
+    maxDelayMs?: number;
+}
+export interface StepAction {
+    /** Operation executed for automation steps. */
+    operation?: OpRef;
+    /** Form rendered for human input steps. */
+    form?: FormRef;
+    /** Effect-free, immutable graph evaluated before Workflow selects an effect. */
+    decisionGraph?: DecisionGraphRef;
+    /** Pinned sub-SOP compiled and run through the Workflow authority. */
+    subSop?: {
+        key: string;
+        revision: number;
+        digest: string;
+    };
+    /** Durable signal that resumes a wait step. */
+    waitSignalKey?: string;
+    /** Named authority scope checked by the Workflow host before dispatch. */
+    authorityScopeRef?: string;
+}
+export interface StepModelHints {
+    /** Preferred benchmark dimension for model selection. */
+    dimension?: string;
+    /** Weighted priorities across multiple dimensions. */
+    priorities?: {
+        dimension: string;
+        weight: number;
+    }[];
+    /** Hard constraints for model filtering. */
+    constraints?: Record<string, unknown>;
+}
+export interface Step {
+    id: string;
+    type: StepType;
+    label: string;
+    description?: string;
+    action?: StepAction;
+    guard?: GuardCondition;
+    timeoutMs?: number;
+    retry?: RetryPolicy;
+    /** Integration slot identifiers required before this step can execute. */
+    requiredIntegrations?: string[];
+    /** Capabilities that must be enabled for this step to execute. */
+    requiredCapabilities?: CapabilityRef[];
+    /** Hints for ranking-driven AI model selection on this step. */
+    modelHints?: StepModelHints;
+    /** Runtime-specific execution metadata for adapter-backed orchestration. */
+    runtime?: WorkflowStepRuntimeConfig;
+}
+export interface Transition {
+    from: string;
+    to: string;
+    label?: string;
+    /** Typed, persistable predicate for all newly authored workflows. */
+    predicate?: PredicateSpec;
+    /** @deprecated Trusted legacy expression. Do not use for creator-authored workflows. */
+    condition?: string;
+}
+export interface SLA {
+    totalDurationMs?: number;
+    stepDurationMs?: Record<string, number>;
+}
+export interface CompensationStep {
+    stepId: string;
+    operation: OpRef;
+    description?: string;
+}
+export interface CompensationStrategy {
+    trigger?: 'on_failure' | 'manual';
+    steps: CompensationStep[];
+}
+/**
+ * A directed edge in a V2 workflow DAG.
+ *
+ * `from` and `to` are `SharedTask.id` references within `WorkflowDefinition.tasks`.
+ * `runIf` is an optional expression evaluated via `evaluateExpression()`.
+ * When `runIf` evaluates to `false` the downstream task is skipped and the skip
+ * propagates to all its dependents (cascade-skip).
+ *
+ * @stability experimental — promoted to stable in P10
+ */
+export interface WorkflowEdge {
+    /** Source task ID (must exist in `tasks[]`). */
+    from: string;
+    /** Target task ID (must exist in `tasks[]`). */
+    to: string;
+    /** Optional guard expression; task is skipped when this evaluates to false. */
+    runIf?: string;
+    /** Typed, persistable predicate for decision branches. */
+    predicate?: PredicateSpec;
+    /**
+     * Explicit condition expression for this edge (alias for `runIf` with richer
+     * semantic intent — preferred for decision-branch edges).
+     * Evaluated after `runIf`; edge is blocked when this returns false.
+     */
+    /** @deprecated Trusted legacy expression. Do not combine with `predicate`. */
+    condition?: string;
+}
+export interface WorkflowDefinition {
+    /**
+     * Will be removed in the next major version.
+     */
+    steps?: Step[];
+    /**
+     * Will be removed in the next major version.
+     */
+    transitions?: Transition[];
+    /**
+     * Will be removed in the next major version.
+     */
+    entryStepId?: string;
+    sla?: SLA;
+    compensation?: CompensationStrategy;
+    /**
+     * V2 DAG task list (A9-compliant {@link SharedTask}, workflow context).
+     * Primary execution shape since P10 (promoted from experimental).
+     */
+    tasks?: SharedTask[];
+    /**
+     * V2 DAG edges connecting tasks. Each edge may carry a `runIf` guard.
+     * V2 is the only supported execution shape since P10.
+     */
+    edges?: WorkflowEdge[];
+}
+export type WorkflowMeta = OwnerShipMeta;
+export interface WorkflowSpec {
+    meta: WorkflowMeta;
+    definition: WorkflowDefinition;
+    /** Optional typed result catalog for workflow-level success/failure outcomes. */
+    results?: ResultCatalog;
+    /** Optional runtime config for adapter-first workflow orchestration. */
+    runtime?: WorkflowRuntimeConfig;
+    /** Optional metadata merged by workflow composition overlays. */
+    metadata?: Record<string, unknown>;
+    /** Optional annotations merged by workflow composition overlays. */
+    annotations?: Record<string, unknown>;
+    policy?: {
+        flags?: string[];
+    };
+    experiments?: ExperimentRef[];
+}
+/**
+ * Helper to define a Workflow.
+ */
+export declare const defineWorkflow: (spec: WorkflowSpec) => WorkflowSpec;
+export declare class WorkflowRegistry extends SpecContractRegistry<'workflow', WorkflowSpec> {
+    constructor(items?: WorkflowSpec[]);
+}
+export declare const tech_workflows_overview_DocBlocks: DocBlock[];

package/dist/workflow/spec.js

@@ -0,0 +1 @@
+import{SpecContractRegistry as t}from"../registry.js";export const defineWorkflow=(e)=>e;export class WorkflowRegistry extends t{constructor(e){super("workflow",e)}}export const tech_workflows_overview_DocBlocks=[{id:"docs.tech.workflows.overview",title:"WorkflowSpec Overview",summary:"WorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review, including runtime adapter capabilities/ports for checkpointing, suspend-resume orchestration, and explicit waiting/retry states. Specs stay inside `@lssm/lib.contracts-spec` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.",kind:"reference",visibility:"public",route:"/docs/tech/workflows/overview",tags:["tech","workflows","overview"],body:"# WorkflowSpec Overview\n\n## Purpose\n\nWorkflowSpec provides a declarative, versioned format for long-running flows that mix automation and human review. Specs stay inside `@lssm/lib.contracts-spec` (`src/workflow/spec.ts`) so the same definition powers runtime execution, documentation, and future generation.\n\n## Core Types\n\n- `WorkflowMeta`: ownership metadata (`title`, `domain`, `owners`, `tags`, `stability`) plus `name` and `version`.\n- `WorkflowDefinition`:\n  - `entryStepId?`: optional explicit entry point (defaults to first step).\n  - `steps[]`: ordered list of `Step` descriptors.\n  - `transitions[]`: directed edges between steps with optional expressions.\n  - `sla?`: aggregated timing hints for the overall flow or per-step budgets.\n  - `compensation?`: fallback operations executed when a workflow is rolled back or fails.\n- `Step`:\n  - `type`: `human`, `automation`, or `decision`.\n  - `action`: references either a `ContractSpec` (`operation`) or `FormSpec` (`form`).\n  - Optional `guard`, `timeoutMs`, and retry policy (`maxAttempts`, `backoff`, `delayMs`, `maxDelayMs?`).\n  - `requiredIntegrations?`: integration slot ids that must be bound before the step may execute.\n  - `requiredCapabilities?`: `CapabilityRef[]` that must be enabled in the resolved app config.\n- `Transition`: `from` \u2192 `to` with optional `condition` string (simple data expressions).\n\n## Registry & Validation\n\n- `defineWorkflow()` is available from `@lssm/lib.contracts-spec/workflow/spec` for safe workflow authoring in VM-evaluated runtimes.\n- `WorkflowRegistry` (`src/workflow/spec.ts`) stores specs by key `<name>.v<version>` and exposes `register`, `list`, and `get`.\n- `validateWorkflowSpec()` (`src/workflow/validation.ts`) checks:\n  - Duplicate step IDs.\n  - Unknown `from`/`to` transitions.\n  - Empty guards/conditions.\n  - Reachability from the entry step.\n  - Cycles in the graph.\n  - Operation/Form references against provided registries.\n- `assertWorkflowSpecValid()` wraps validation and throws `WorkflowValidationError` when errors remain.\n\n## Runtime\n\n- `WorkflowRunner` (`src/workflow/runner.ts`) executes workflows and coordinates steps.\n  - `start(name, version?, initialData?)` returns a `workflowId`.\n  - `executeStep(workflowId, input?)` runs the current step (automation or human).\n  - `getState(workflowId)` retrieves the latest state snapshot.\n  - `cancel(workflowId)` marks the workflow as cancelled.\n  - `preFlightCheck(name, version?, resolvedConfig?)` evaluates integration/capability requirements before the workflow starts.\n  - Throws `WorkflowPreFlightError` if required integration slots are unbound or required capabilities are disabled.\n- `StateStore` (`src/workflow/state.ts`) abstracts persistence. V1 ships with:\n  - `InMemoryStateStore` (`src/workflow/adapters/memory-store.ts`) for tests/dev.\n  - Placeholder factories for file/database adapters (`adapters/file-adapter.ts`, `adapters/db-adapter.ts`).\n- Guard evaluation: expression guards run through `evaluateExpression()` (`src/workflow/expression.ts`); custom policy guards can be provided via `guardEvaluator`.\n- Events: the runner emits `workflow.started`, `workflow.step_completed`, `workflow.step_failed`, and `workflow.cancelled` through the optional `eventEmitter`.\n- React bindings (`@lssm/lib.presentation-runtime-react`):\n  - `useWorkflow` hook (polls state, exposes `executeStep`, `cancel`, `refresh`).\n  - `WorkflowStepper` progress indicator using design-system Stepper.\n  - `WorkflowStepRenderer` helper to render human/automation/decision steps with sensible fallbacks.\n\n## Authoring Checklist\n\n1. Reuse existing operations/forms; create new specs when missing.\n2. Prefer explicit `entryStepId` for clarity (especially with decision branches).\n3. Give automation steps an `operation` and human steps a `form` (warnings surface otherwise).\n4. Use short, meaningful step IDs (`submit`, `review`, `finalize`) to simplify analytics.\n5. Keep guard expressions deterministic; complex policy logic should move to PolicySpec (Phase 2).\n6. For Vercel Workflow or other VM-evaluated runtimes, import `defineWorkflow` and `WorkflowSpec` from `@lssm/lib.contracts-spec/workflow/spec`.\n\n## Testing\n\n- Add unit tests for new workflows via `assertWorkflowSpecValid`.\n- Use the new Vitest suites (`validation.test.ts`, `expression.test.ts`, `runner.test.ts`) as examples.\n- CLI support will arrive in Phase 1 PR 3 (`contractspec create --type workflow`).\n\n## Tooling\n\n- `contractspec create --type workflow` scaffolds a WorkflowSpec with interactive prompts.\n- `contractspec build <spec.workflow.ts>` generates a runner scaffold (`.runner.ts`) wired to `WorkflowRunner` and the in-memory store.\n- `contractspec validate` understands `.workflow.ts` files and checks core structure (meta, steps, transitions).\n\n## Next Steps (Non-MVP)\n\n- Persistence adapters (database/file) for workflow state (Phase 2).\n- React bindings (`useWorkflow`, `WorkflowStepper`) and presentation-runtime integration (PR 3).\n- Policy engine integration (`guard.type === 'policy'` validated against PolicySpec).\n- Telemetry hooks for step execution metrics.\n\n"}];

package/dist/workflow/state.d.ts

@@ -0,0 +1,46 @@
+import type { ContractProblem, ContractSuccess } from '../results/index.js';
+import type { WorkflowStatus } from './spec.js';
+export type WorkflowWaitReason = 'approval' | 'hook' | 'human_input' | 'retry' | 'stream' | 'webhook';
+export interface StepExecution {
+    stepId: string;
+    startedAt: Date;
+    completedAt?: Date;
+    status: 'pending' | 'running' | 'waiting' | 'completed' | 'failed';
+    input?: unknown;
+    output?: unknown;
+    result?: ContractSuccess<unknown, string>;
+    error?: string;
+    problem?: ContractProblem<string, Record<string, unknown>>;
+}
+export interface WorkflowWaitState {
+    reason: WorkflowWaitReason;
+    stepId: string;
+    requestedAt: Date;
+    retryAt?: Date;
+    metadata?: Record<string, string>;
+}
+export interface WorkflowState<Data extends Record<string, unknown> = Record<string, unknown>> {
+    workflowId: string;
+    traceId?: string;
+    workflowName: string;
+    workflowVersion: string;
+    currentStep: string;
+    data: Data;
+    result?: ContractSuccess<unknown, string>;
+    problem?: ContractProblem<string, Record<string, unknown>>;
+    retryCounts?: Record<string, number>;
+    history: StepExecution[];
+    status: WorkflowStatus;
+    wait?: WorkflowWaitState;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface WorkflowStateFilters {
+    status?: WorkflowStatus;
+}
+export interface StateStore {
+    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[]>;
+}

package/dist/workflow/validation-workflow-devkit.d.ts

@@ -0,0 +1,3 @@
+import type { WorkflowSpec } from './spec.js';
+import type { WorkflowValidationIssue } from './validation.js';
+export declare function validateWorkflowDevkitConfig(spec: WorkflowSpec, issues: WorkflowValidationIssue[]): void;

package/dist/workflow/validation-workflow-devkit.js

@@ -0,0 +1 @@
+export function validateWorkflowDevkitConfig(e,o){if(!Boolean(e.runtime?.workflowDevkit||e.runtime?.capabilities?.adapters?.["workflow-devkit"]))return;const t=e.runtime?.workflowDevkit;if(!t){o.push({level:"warning",message:"Workflow enables the workflow-devkit adapter without defining runtime.workflowDevkit."});return}k(t.runIdentity?.prefix,"runtime.workflowDevkit.runIdentity.prefix",o);k(t.hookTokens?.prefix,"runtime.workflowDevkit.hookTokens.prefix",o);const l=t.serialization?.mode??"strict";if(l==="strict"){if((t.serialization?.enforceMetadata??!0)&&e.metadata!==void 0&&!n(e.metadata))f(o,"Workflow metadata must be JSON-serializable.");if((t.serialization?.enforceMetadata??!0)&&e.annotations!==void 0&&!n(e.annotations))f(o,"Workflow annotations must be JSON-serializable.")}for(const d of e.definition.steps??[])s(d,l,o)}function s(e,o,i){const t=e.runtime?.workflowDevkit;if(!t){if(e.type==="human")i.push({level:"warning",message:`Human step "${e.id}" does not define runtime.workflowDevkit wait behavior.`});return}u(e.id,t,i);if(e.type==="automation"&&e.retry&&(!t.idempotencyKey||t.idempotencyKey.trim().length===0))i.push({level:"error",message:`Retrying automation step "${e.id}" must define runtime.workflowDevkit.idempotencyKey.`});if(t.idempotencyKey!==void 0&&t.idempotencyKey.trim().length===0)i.push({level:"error",message:`Step "${e.id}" defines an empty runtime.workflowDevkit.idempotencyKey.`});if(o==="strict"){r(e.id,"runtime.workflowDevkit.stateExample",t.stateExample,i);r(e.id,"runtime.workflowDevkit.hookWait.payloadExample",t.hookWait?.payloadExample,i);r(e.id,"runtime.workflowDevkit.webhookWait.payloadExample",t.webhookWait?.payloadExample,i);r(e.id,"runtime.workflowDevkit.approvalWait.payloadExample",t.approvalWait?.payloadExample,i);r(e.id,"runtime.workflowDevkit.streamSession.initialState",t.streamSession?.initialState,i)}}function u(e,o,i){switch(o.behavior){case"sleep":if(!o.sleep?.duration.trim())w(e,o.behavior,"sleep.duration",i);return;case"hookWait":if(o.hookWait?.resumeSource!=="hook")a(e,o.behavior,"hook",i);return;case"webhookWait":if(o.webhookWait?.resumeSource!=="webhook")a(e,o.behavior,"webhook",i);return;case"approvalWait":if(o.approvalWait?.resumeSource!=="approval")a(e,o.behavior,"approval",i);return;case"streamSession":if(o.streamSession?.resumeSource!=="stream")a(e,o.behavior,"stream",i);return}}function w(e,o,i,t){t.push({level:"error",message:`Step "${e}" configures ${o} but is missing ${i}.`})}function f(e,o){e.push({level:"error",message:o})}function a(e,o,i,t){t.push({level:"error",message:`Step "${e}" configures ${o} but does not declare resumeSource "${i}".`})}function r(e,o,i,t){if(i===void 0)return;if(!n(i))t.push({level:"error",message:`Step "${e}" field ${o} must be JSON-serializable.`})}function k(e,o,i){if(e!==void 0&&e.trim().length===0)i.push({level:"error",message:`${o} must not be empty when provided.`})}function n(e,o=new Set){if(e===null||typeof e==="boolean"||typeof e==="number"||typeof e==="string")return!0;if(typeof e==="bigint"||typeof e==="function"||typeof e==="symbol"||e===void 0)return!1;if(o.has(e))return!1;o.add(e);if(Array.isArray(e))return e.every((i)=>n(i,o));if(Object.getPrototypeOf(e)!==Object.prototype)return!1;return Object.values(e).every((i)=>n(i,o))}

package/dist/workflow/validation.d.ts

@@ -0,0 +1,93 @@
+import type { FormRegistry } from '../forms/index.js';
+import type { OperationSpecRegistry } from '../operations/registry.js';
+import type { WorkflowSpec } from './spec.js';
+export type WorkflowValidationLevel = 'error' | 'warning';
+export interface WorkflowValidationIssue {
+    level: WorkflowValidationLevel;
+    message: string;
+    context?: Record<string, unknown>;
+}
+export interface ValidateWorkflowSpecOptions {
+    operations?: OperationSpecRegistry;
+    forms?: FormRegistry;
+}
+export declare class WorkflowValidationError extends Error {
+    readonly issues: WorkflowValidationIssue[];
+    constructor(message: string, issues: WorkflowValidationIssue[]);
+}
+/**
+ * Validate workflow structure, references, and reachability.
+ *
+ * Supports both shapes:
+ * - **V1** (`steps[]` + `transitions[]`): validates step ids, transitions, guards, reachability, and cycles.
+ * - **V2** (`tasks[]` + `edges[]`): validates A9 invariants per task and detects cycles in the DAG.
+ *
+ * When both shapes are present the validator runs **both passes** (dual-shape validation).
+ * Returns the collected issues. Consumers may call {@link assertWorkflowSpecValid}
+ * to throw on validation errors.
+ */
+export declare function validateWorkflowSpec(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): WorkflowValidationIssue[];
+export declare function assertWorkflowSpecValid(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): void;
+import type { CapabilityRegistry } from '../capabilities/capabilities.js';
+import type { EventRegistry } from '../events.js';
+import type { WorkflowRegistry } from './spec.js';
+export interface WorkflowConsistencyDeps {
+    workflows: WorkflowRegistry;
+    operations?: OperationSpecRegistry;
+    forms?: FormRegistry;
+    events?: EventRegistry;
+    capabilities?: CapabilityRegistry;
+}
+export interface WorkflowValidationResult {
+    valid: boolean;
+    issues: WorkflowValidationIssue[];
+}
+/**
+ * Validate workflow consistency across registries.
+ *
+ * Checks that:
+ * - All workflow specs are internally valid
+ * - Operations referenced by steps exist
+ * - Forms referenced by steps exist
+ * - Capabilities required by steps exist
+ *
+ * @param deps - Registry dependencies
+ * @returns Validation result
+ */
+export declare function validateWorkflowConsistency(deps: WorkflowConsistencyDeps): WorkflowValidationResult;
+/**
+ * Assert workflow consistency across registries.
+ *
+ * @param deps - Registry dependencies
+ * @throws {WorkflowValidationError} If validation fails
+ */
+export declare function assertWorkflowConsistency(deps: WorkflowConsistencyDeps): void;
+/**
+ * Validate SLA configuration is reasonable.
+ *
+ * @param spec - Workflow spec to validate
+ * @returns Array of validation issues
+ */
+export declare function validateSlaConfig(spec: WorkflowSpec): WorkflowValidationIssue[];
+/**
+ * Validate compensation configuration.
+ *
+ * @param spec - Workflow spec to validate
+ * @returns Array of validation issues
+ */
+export declare function validateCompensation(spec: WorkflowSpec): WorkflowValidationIssue[];
+/**
+ * Validate retry configuration.
+ *
+ * @param spec - Workflow spec to validate
+ * @returns Array of validation issues
+ */
+export declare function validateRetryConfig(spec: WorkflowSpec): WorkflowValidationIssue[];
+/**
+ * Perform comprehensive workflow validation.
+ *
+ * @param spec - Workflow spec to validate
+ * @param options - Validation options
+ * @returns Validation result
+ */
+export declare function validateWorkflowComprehensive(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): WorkflowValidationResult;

package/dist/workflow/validation.js

@@ -0,0 +1 @@
+import{validatePredicateSpec as d}from"../decisioning/predicate.js";import{validateWorkflowTask as u}from"../shared-entities/task-validators.js";import{validateWorkflowDevkitConfig as m}from"./validation-workflow-devkit.js";export class WorkflowValidationError extends Error{issues;constructor(s,o){super(s);this.issues=o;this.name="WorkflowValidationError"}}export function validateWorkflowSpec(s,o={}){const e=[],{definition:i}=s,n=Boolean(i.tasks?.length);if(!(i.steps?.length??0)&&!n){e.push({level:"error",message:"Workflow must declare at least one step."});return e}if(i.steps?.length){const r=k(i,e),t=i.entryStepId??i.steps?.[0]?.id??null;if(!t)e.push({level:"error",message:"Workflow requires an entry step (definition.entryStepId)."});else if(!r.has(t))e.push({level:"error",message:`Entry step "${t}" is not defined in steps.`});const l=v(i,r,e);W(i.steps??[],o,e);S(t,r,l,e);I(l,e)}y(s,e);m(s,e);if(n){g(i.tasks,e);w(i.tasks,i.edges??[],e)}return e}function g(s,o){const e=new Set;for(const i of s){if(e.has(i.id))o.push({level:"error",message:`Duplicate task id "${i.id}" in DAG tasks[].`});e.add(i.id);const n=u(i);if(!n.valid)o.push({level:"error",message:n.error})}}function w(s,o,e){const i=new Set(s.map((a)=>a.id));for(const a of o){if(!i.has(a.from))e.push({level:"error",message:`DAG edge references unknown task "${a.from}" in 'from'.`});if(!i.has(a.to))e.push({level:"error",message:`DAG edge references unknown task "${a.to}" in 'to'.`});f(a,`DAG edge ${a.from} -> ${a.to}`,e)}const n=new Map(s.map((a)=>[a.id,new Set]));for(const a of o)n.get(a.from)?.add(a.to);const r=new Set,t=new Set;let l=!1;const p=(a)=>{if(t.has(a)){if(!l){e.push({level:"error",message:`DAG tasks contain a cycle involving task "${a}".`});l=!0}return}if(r.has(a))return;t.add(a);for(const c of n.get(a)??[])p(c);t.delete(a);r.add(a)};for(const a of n.keys())p(a)}export function assertWorkflowSpecValid(s,o={}){const e=validateWorkflowSpec(s,o);if(e.filter((n)=>n.level==="error").length)throw new WorkflowValidationError(`Workflow ${s.meta.key}.v${s.meta.version} is invalid`,e)}function k(s,o){const e=new Map;for(const i of s.steps??[]){if(e.has(i.id)){o.push({level:"error",message:`Duplicate step id "${i.id}" detected.`});continue}e.set(i.id,i);if(i.type==="automation"&&!i.action?.operation)o.push({level:"warning",message:`Automation step "${i.id}" does not declare an operation.`});if(i.type==="human"&&!i.action?.form)o.push({level:"warning",message:`Human step "${i.id}" does not declare a form.`});if(i.guard&&!i.guard.value.trim())o.push({level:"error",message:`Guard for step "${i.id}" must have a non-empty value.`})}return e}function v(s,o,e){const i=new Map,n=new Map;for(const t of o.keys()){i.set(t,new Set);n.set(t,0)}for(const t of s.transitions??[]){const l=o.get(t.from),p=o.get(t.to);if(!l){e.push({level:"error",message:`Transition refers to unknown "from" step "${t.from}".`});continue}if(!p){e.push({level:"error",message:`Transition refers to unknown "to" step "${t.to}".`});continue}i.get(t.from)?.add(t.to);n.set(t.to,(n.get(t.to)??0)+1);h(t,e)}const r=[...n.entries()].filter(([,t])=>t===0).map(([t])=>t);if(r.length>1)e.push({level:"warning",message:`Workflow has multiple potential entry steps: ${r.join(", ")}`});return i}function h(s,o){if(s.condition&&!s.condition.trim())o.push({level:"error",message:`Transition ${s.from} -> ${s.to} declares an empty condition.`});f(s,`Transition ${s.from} -> ${s.to}`,o)}function f(s,o,e){if(s.predicate&&(s.condition!==void 0||s.runIf!==void 0))e.push({level:"error",message:`${o} cannot combine a typed predicate with a legacy expression.`});if(!s.predicate)return;for(const i of d(s.predicate))e.push({level:"error",message:`${o} has an invalid predicate at ${i.path}: ${i.message}`})}function y(s,o){const e=s.runtime;if(!e)return;const i=e.capabilities?.adapters;if(i){const r=Object.entries(i).filter(([,t])=>Boolean(t)).map(([t])=>t);if(r.length>1)o.push({level:"warning",message:`Workflow enables multiple runtime adapters (${r.join(", ")}). Ensure adapter routing is deterministic.`})}const n=e.ports;if(!n)return;for(const[r,t]of Object.entries(n)){if(t===void 0)continue;if(t.trim().length===0)o.push({level:"error",message:`Workflow runtime port "${r}" must not be empty when provided.`})}if(e.capabilities?.checkpointing&&!n.checkpointStore)o.push({level:"warning",message:"Workflow enables checkpointing without defining runtime.ports.checkpointStore."});if(e.capabilities?.suspendResume&&!n.suspension)o.push({level:"warning",message:"Workflow enables suspend/resume without defining runtime.ports.suspension."});if(e.capabilities?.approvalGateway&&!n.approvalGateway)o.push({level:"warning",message:"Workflow enables approval gateway without defining runtime.ports.approvalGateway."})}function W(s,o,e){for(const i of s){const n=i.action;if(!n)continue;if(n.operation&&o.operations){if(!o.operations.get(n.operation.key,n.operation.version))e.push({level:"error",message:`Step "${i.id}" references unknown operation ${n.operation.key}.v${n.operation.version}.`})}if(n.form&&o.forms){if(!o.forms.get(n.form.key,n.form.version))e.push({level:"error",message:`Step "${i.id}" references unknown form ${n.form.key}.v${n.form.version}.`})}}}function S(s,o,e,i){if(!s||!o.has(s))return;const n=new Set,r=[s];n.add(s);while(r.length){const t=r.shift();if(!t)continue;const l=e.get(t);if(!l)continue;for(const p of l){if(n.has(p))continue;n.add(p);r.push(p)}}for(const t of o.keys())if(!n.has(t))i.push({level:"error",message:`Step "${t}" is unreachable from entry step "${s}".`})}function I(s,o){const e=new Set,i=new Set;let n=!1;const r=(t)=>{if(i.has(t)){if(!n){o.push({level:"error",message:`Workflow contains a cycle involving step "${t}".`});n=!0}return}if(e.has(t))return;i.add(t);const l=s.get(t);if(l)for(const p of l)r(p);i.delete(t);e.add(t)};for(const t of s.keys())r(t)}export function validateWorkflowConsistency(s){const o=[];for(const e of s.workflows.list()){const i={operations:s.operations,forms:s.forms},n=validateWorkflowSpec(e,i);o.push(...n.map((r)=>({...r,message:`[${e.meta.key}.v${e.meta.version}] ${r.message}`})));if(s.capabilities){for(const r of e.definition.steps??[])for(const t of r.requiredCapabilities??[])if(!s.capabilities.get(t.key,t.version))o.push({level:"error",message:`[${e.meta.key}.v${e.meta.version}] Step "${r.id}" references unknown capability "${t.key}.v${t.version}"`,context:{stepId:r.id,capability:t}})}if(e.definition.compensation&&s.operations){for(const r of e.definition.compensation.steps)if(!s.operations.get(r.operation.key,r.operation.version))o.push({level:"error",message:`[${e.meta.key}.v${e.meta.version}] Compensation for step "${r.stepId}" references unknown operation "${r.operation.key}.v${r.operation.version}"`,context:{stepId:r.stepId,operation:r.operation}})}if(e.definition.sla?.stepDurationMs){const r=new Set((e.definition.steps??[]).map((t)=>t.id));for(const t of Object.keys(e.definition.sla.stepDurationMs))if(!r.has(t))o.push({level:"warning",message:`[${e.meta.key}.v${e.meta.version}] SLA references unknown step "${t}"`,context:{stepId:t}})}}return{valid:o.filter((e)=>e.level==="error").length===0,issues:o}}export function assertWorkflowConsistency(s){const o=validateWorkflowConsistency(s);if(!o.valid)throw new WorkflowValidationError("Workflow consistency check failed",o.issues)}export function validateSlaConfig(s){const o=[],e=s.definition.sla;if(!e)return o;if(e.totalDurationMs!==void 0&&e.totalDurationMs<=0)o.push({level:"error",message:"SLA totalDurationMs must be positive",context:{totalDurationMs:e.totalDurationMs}});if(e.stepDurationMs){for(const[n,r]of Object.entries(e.stepDurationMs))if(r<=0)o.push({level:"error",message:`SLA stepDurationMs for "${n}" must be positive`,context:{stepId:n,duration:r}});const i=Object.values(e.stepDurationMs).reduce((n,r)=>n+r,0);if(e.totalDurationMs&&i>e.totalDurationMs)o.push({level:"warning",message:`Sum of step durations (${i}ms) exceeds total duration (${e.totalDurationMs}ms)`,context:{stepDurationsSum:i,totalDurationMs:e.totalDurationMs}})}return o}export function validateCompensation(s){const o=[],e=s.definition.compensation;if(!e)return o;const i=new Set((s.definition.steps??[]).map((t)=>t.id)),n=new Set;for(const t of e.steps){if(!i.has(t.stepId))o.push({level:"error",message:`Compensation references unknown step "${t.stepId}"`,context:{stepId:t.stepId}});if(n.has(t.stepId))o.push({level:"warning",message:`Multiple compensation handlers for step "${t.stepId}"`,context:{stepId:t.stepId}});n.add(t.stepId);if(!t.operation?.key||!t.operation?.version)o.push({level:"error",message:`Compensation for step "${t.stepId}" must specify operation with key and version`,context:{stepId:t.stepId}})}const r=(s.definition.steps??[]).filter((t)=>t.type==="automation");for(const t of r)if(!n.has(t.id))o.push({level:"warning",message:`Automation step "${t.id}" has no compensation handler`,context:{stepId:t.id}});return o}export function validateRetryConfig(s){const o=[];for(const e of s.definition.steps??[]){if(!e.retry)continue;if(e.retry.maxAttempts<=0)o.push({level:"error",message:`Step "${e.id}" retry maxAttempts must be positive`,context:{stepId:e.id,maxAttempts:e.retry.maxAttempts}});if(e.retry.delayMs<=0)o.push({level:"error",message:`Step "${e.id}" retry delayMs must be positive`,context:{stepId:e.id,delayMs:e.retry.delayMs}});if(e.retry.maxDelayMs!==void 0&&e.retry.maxDelayMs<e.retry.delayMs)o.push({level:"warning",message:`Step "${e.id}" retry maxDelayMs (${e.retry.maxDelayMs}) is less than delayMs (${e.retry.delayMs})`,context:{stepId:e.id}})}return o}export function validateWorkflowComprehensive(s,o={}){const e=[];e.push(...validateWorkflowSpec(s,o));e.push(...validateSlaConfig(s));e.push(...validateCompensation(s));e.push(...validateRetryConfig(s));return{valid:e.filter((i)=>i.level==="error").length===0,issues:e}}

package/dist/workflow/workflow-devkit.d.ts

@@ -0,0 +1,74 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type WorkflowDevkitHostTarget = 'generic' | 'next';
+export type WorkflowDevkitIntegrationMode = 'generated' | 'manual';
+export type WorkflowDevkitRunIdentityStrategy = 'meta-key-version' | 'trace-id' | 'workflow-id';
+export type WorkflowDevkitHookTokenStrategy = 'deterministic' | 'session-scoped' | 'step-scoped';
+export type WorkflowDevkitSerializationMode = 'passthrough' | 'strict';
+export type WorkflowDevkitResumeSource = 'approval' | 'hook' | 'stream' | 'webhook';
+export type WorkflowDevkitStepBehavior = 'approvalWait' | 'hookWait' | 'sleep' | 'streamSession' | 'webhookWait';
+export interface WorkflowDevkitSerializationConfig {
+    enforceHookPayloads?: boolean;
+    enforceMetadata?: boolean;
+    enforceWorkflowState?: boolean;
+    mode?: WorkflowDevkitSerializationMode;
+}
+export interface WorkflowDevkitIdentityConfig {
+    prefix?: string;
+    strategy?: WorkflowDevkitRunIdentityStrategy;
+}
+export interface WorkflowDevkitHookTokenConfig {
+    prefix?: string;
+    strategy?: WorkflowDevkitHookTokenStrategy;
+}
+export interface WorkflowDevkitRuntimeConfig {
+    hostTarget?: WorkflowDevkitHostTarget;
+    hookTokens?: WorkflowDevkitHookTokenConfig;
+    integrationMode?: WorkflowDevkitIntegrationMode;
+    runIdentity?: WorkflowDevkitIdentityConfig;
+    serialization?: WorkflowDevkitSerializationConfig;
+}
+export interface WorkflowDevkitSleepStepConfig {
+    duration: string;
+}
+export interface WorkflowDevkitHookWaitStepConfig {
+    collect?: boolean;
+    payloadExample?: JsonValue;
+    resumeSource: Extract<WorkflowDevkitResumeSource, 'hook'>;
+    token?: string;
+}
+export interface WorkflowDevkitWebhookWaitStepConfig {
+    method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+    path?: string;
+    payloadExample?: JsonValue;
+    resumeSource: Extract<WorkflowDevkitResumeSource, 'webhook'>;
+    token?: string;
+}
+export interface WorkflowDevkitApprovalWaitStepConfig {
+    channel?: string;
+    payloadExample?: JsonValue;
+    resumeSource: Extract<WorkflowDevkitResumeSource, 'approval'>;
+    token?: string;
+}
+export interface WorkflowDevkitStreamSessionStepConfig {
+    followUpToken?: string;
+    initialState?: JsonValue;
+    keepAlive?: boolean;
+    resumeSource: Extract<WorkflowDevkitResumeSource, 'stream'>;
+    sessionKey?: string;
+}
+export interface WorkflowDevkitStepRuntimeConfig {
+    approvalWait?: WorkflowDevkitApprovalWaitStepConfig;
+    behavior: WorkflowDevkitStepBehavior;
+    hookWait?: WorkflowDevkitHookWaitStepConfig;
+    idempotencyKey?: string;
+    sleep?: WorkflowDevkitSleepStepConfig;
+    stateExample?: JsonValue;
+    streamSession?: WorkflowDevkitStreamSessionStepConfig;
+    webhookWait?: WorkflowDevkitWebhookWaitStepConfig;
+}
+export interface WorkflowStepRuntimeConfig {
+    workflowDevkit?: WorkflowDevkitStepRuntimeConfig;
+}

package/dist/workflow/workflow-sdk.d.ts

@@ -0,0 +1,8 @@
+import { type ContractProblem } from '../results/index.js';
+export interface WorkflowSdkErrorConstructors {
+    FatalError: new (message: string, options?: Record<string, unknown>) => Error;
+    RetryableError: new (message: string, options?: Record<string, unknown>) => Error;
+}
+export declare function toWorkflowSdkError(error: unknown, constructors: WorkflowSdkErrorConstructors): Error;
+export declare function problemToWorkflowSdkError(problem: ContractProblem<string, Record<string, unknown>>, constructors: WorkflowSdkErrorConstructors): Error;
+export declare function throwWorkflowSdkError(error: unknown, constructors: WorkflowSdkErrorConstructors): never;

package/dist/workflow/workflow-sdk.js

@@ -0,0 +1 @@
+import{ContractSpecError as e,normalizeContractError as s}from"../results/index.js";export function toWorkflowSdkError(r,o){const t=s(r,{source:{service:"workflow"}});return problemToWorkflowSdkError(t.problem,o)}export function problemToWorkflowSdkError(r,o){const t=r.detail??r.title,n={code:r.code,status:r.status,retryAfter:r.retryAfter,problem:r};if(r.retryable)return new o.RetryableError(t,n);return new o.FatalError(t,n)}export function throwWorkflowSdkError(r,o){throw toWorkflowSdkError(r instanceof e?r.problem:r,o)}