@lssm/lib.contracts 0.0.0-canary-20251217054315 → 0.0.0-canary-20251217060433

package/dist/workflow/spec.d.ts

@@ -0,0 +1,99 @@
+import { OwnerShipMeta } from "../ownership.js";
+import { CapabilityRef } from "../capabilities.js";
+import { ExperimentRef } from "../experiments/spec.js";
+import { OpRef } from "../features.js";
+
+//#region src/workflow/spec.d.ts
+
+/**
+ * Reference to a form spec declared in {@link FormRegistry}.
+ */
+interface FormRef {
+  key: string;
+  version: number;
+}
+type StepType = 'human' | 'automation' | 'decision';
+type WorkflowStatus = 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type GuardConditionKind = 'policy' | 'expression';
+interface GuardCondition {
+  type: GuardConditionKind;
+  /** Policy name or expression string depending on the type. */
+  value: string;
+}
+interface RetryPolicy {
+  maxAttempts: number;
+  backoff: 'linear' | 'exponential';
+  delayMs: number;
+  /** Optional max delay cap for exponential backoff. */
+  maxDelayMs?: number;
+}
+interface StepAction {
+  /** Operation executed for automation steps. */
+  operation?: OpRef;
+  /** Form rendered for human input steps. */
+  form?: FormRef;
+}
+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[];
+}
+interface Transition {
+  from: string;
+  to: string;
+  label?: string;
+  /** Expression evaluated against workflow data (e.g., `data.approved === true`). */
+  condition?: string;
+}
+interface SLA {
+  totalDurationMs?: number;
+  stepDurationMs?: Record<string, number>;
+}
+interface CompensationStep {
+  stepId: string;
+  operation: OpRef;
+  description?: string;
+}
+interface CompensationStrategy {
+  trigger?: 'on_failure' | 'manual';
+  steps: CompensationStep[];
+}
+interface WorkflowDefinition {
+  steps: Step[];
+  transitions: Transition[];
+  /** Optional explicit entry step. Defaults to the first step when omitted. */
+  entryStepId?: string;
+  sla?: SLA;
+  compensation?: CompensationStrategy;
+}
+interface WorkflowMeta extends OwnerShipMeta {
+  /** Fully-qualified workflow name (e.g., `sigil.onboarding.basic`). */
+  name: string;
+  /** Version of the workflow. Increment on breaking changes. */
+  version: number;
+}
+interface WorkflowSpec {
+  meta: WorkflowMeta;
+  definition: WorkflowDefinition;
+  policy?: {
+    flags?: string[];
+  };
+  experiments?: ExperimentRef[];
+}
+declare class WorkflowRegistry {
+  private readonly items;
+  register(spec: WorkflowSpec): this;
+  list(): WorkflowSpec[];
+  get(name: string, version?: number): WorkflowSpec | undefined;
+}
+//#endregion
+export { CompensationStep, CompensationStrategy, FormRef, GuardCondition, GuardConditionKind, RetryPolicy, SLA, Step, StepAction, StepType, Transition, WorkflowDefinition, WorkflowMeta, WorkflowRegistry, WorkflowSpec, WorkflowStatus };

package/dist/workflow/state.d.ts

@@ -0,0 +1,35 @@
+import { WorkflowStatus } from "./spec.js";
+
+//#region src/workflow/state.d.ts
+interface StepExecution {
+  stepId: string;
+  startedAt: Date;
+  completedAt?: Date;
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+}
+interface WorkflowState {
+  workflowId: string;
+  workflowName: string;
+  workflowVersion: number;
+  currentStep: string;
+  data: Record<string, unknown>;
+  retryCounts?: Record<string, number>;
+  history: StepExecution[];
+  status: WorkflowStatus;
+  createdAt: Date;
+  updatedAt: Date;
+}
+interface WorkflowStateFilters {
+  status?: WorkflowStatus;
+}
+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[]>;
+}
+//#endregion
+export { StateStore, StepExecution, WorkflowState, WorkflowStateFilters };

package/dist/workflow/validation.d.ts

@@ -0,0 +1,28 @@
+import { WorkflowSpec } from "./spec.js";
+import { SpecRegistry } from "../registry.js";
+import { FormRegistry } from "../forms.js";
+
+//#region src/workflow/validation.d.ts
+type WorkflowValidationLevel = 'error' | 'warning';
+interface WorkflowValidationIssue {
+  level: WorkflowValidationLevel;
+  message: string;
+  context?: Record<string, unknown>;
+}
+interface ValidateWorkflowSpecOptions {
+  operations?: SpecRegistry;
+  forms?: FormRegistry;
+}
+declare class WorkflowValidationError extends Error {
+  readonly issues: WorkflowValidationIssue[];
+  constructor(message: string, issues: WorkflowValidationIssue[]);
+}
+/**
+ * Validate workflow structure, references, and reachability.
+ * Returns the collected issues. Consumers may call {@link assertWorkflowSpecValid}
+ * to throw on validation errors.
+ */
+declare function validateWorkflowSpec(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): WorkflowValidationIssue[];
+declare function assertWorkflowSpecValid(spec: WorkflowSpec, options?: ValidateWorkflowSpecOptions): void;
+//#endregion
+export { ValidateWorkflowSpecOptions, WorkflowValidationError, WorkflowValidationIssue, WorkflowValidationLevel, assertWorkflowSpecValid, validateWorkflowSpec };