@vorionsys/atsf-core 0.1.0 → 0.2.1

package/dist/governance/fluid-workflow.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Fluid Workflow State Machine
+ *
+ * Implements three-tier governance (GREEN/YELLOW/RED) with refinement support.
+ * Wraps the governance engine to provide fluid decision-making.
+ *
+ * @packageDocumentation
+ */
+import type { ID } from '../common/types.js';
+import type { GovernanceEngine, GovernanceRequest, GovernanceResult } from './index.js';
+/**
+ * Decision tier for fluid governance
+ */
+export type DecisionTier = 'GREEN' | 'YELLOW' | 'RED';
+/**
+ * Refinement action types
+ */
+export type RefinementAction = 'REDUCE_SCOPE' | 'ADD_CONSTRAINTS' | 'REQUEST_APPROVAL' | 'PROVIDE_CONTEXT' | 'DECOMPOSE' | 'WAIT_FOR_TRUST';
+/**
+ * Workflow state
+ */
+export type WorkflowState = 'SUBMITTED' | 'EVALUATING' | 'APPROVED' | 'PENDING_REFINEMENT' | 'PENDING_REVIEW' | 'DENIED' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'EXPIRED';
+/**
+ * Refinement option presented to agent
+ */
+export interface RefinementOption {
+    id: string;
+    action: RefinementAction;
+    description: string;
+    successProbability: number;
+    effort: 'low' | 'medium' | 'high';
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Fluid decision - extends governance result with tier
+ */
+export interface FluidDecision {
+    /** Unique decision ID */
+    decisionId: string;
+    /** Decision tier */
+    tier: DecisionTier;
+    /** Underlying governance result */
+    governanceResult: GovernanceResult;
+    /** Refinement options for YELLOW decisions */
+    refinementOptions?: RefinementOption[];
+    /** Refinement deadline */
+    refinementDeadline?: Date;
+    /** Max refinement attempts */
+    maxRefinementAttempts: number;
+    /** Current attempt */
+    refinementAttempt: number;
+    /** Original decision ID if refined */
+    originalDecisionId?: string;
+    /** For RED: is this a hard denial? */
+    hardDenial?: boolean;
+    /** Violated policies */
+    violatedPolicies?: Array<{
+        policyId: string;
+        name: string;
+        severity: string;
+    }>;
+    /** Created timestamp */
+    createdAt: Date;
+}
+/**
+ * State transition record
+ */
+export interface StateTransition {
+    from: WorkflowState;
+    to: WorkflowState;
+    reason: string;
+    timestamp: Date;
+    decisionId?: string;
+}
+/**
+ * Workflow instance
+ */
+export interface WorkflowInstance {
+    workflowId: string;
+    intentId: string;
+    agentId: string;
+    correlationId: string;
+    state: WorkflowState;
+    decisions: FluidDecision[];
+    currentDecisionId?: string;
+    stateHistory: StateTransition[];
+    createdAt: Date;
+    updatedAt: Date;
+    expiresAt: Date;
+}
+/**
+ * Refinement request from agent
+ */
+export interface RefinementRequest {
+    workflowId: string;
+    selectedRefinements: string[];
+    modifiedRequest?: Partial<GovernanceRequest>;
+    context?: Record<string, unknown>;
+}
+/**
+ * Configuration for fluid workflow
+ */
+export interface FluidWorkflowConfig {
+    /** Default refinement deadline in ms */
+    refinementDeadlineMs: number;
+    /** Max refinement attempts */
+    maxRefinementAttempts: number;
+    /** Workflow expiry in ms */
+    workflowExpiryMs: number;
+    /** Trust threshold for GREEN (0-1) */
+    greenThreshold: number;
+    /** Trust threshold for YELLOW (0-1) - below this is RED */
+    yellowThreshold: number;
+}
+/**
+ * Fluid Workflow Engine
+ *
+ * Manages the lifecycle of intents through three-tier governance.
+ */
+export declare class FluidWorkflowEngine {
+    private config;
+    private governanceEngine;
+    private workflows;
+    constructor(governanceEngine: GovernanceEngine, config?: Partial<FluidWorkflowConfig>);
+    /**
+     * Submit a new intent for governance evaluation
+     */
+    submit(request: GovernanceRequest): Promise<{
+        workflow: WorkflowInstance;
+        decision: FluidDecision;
+    }>;
+    /**
+     * Evaluate a governance request and produce a fluid decision
+     */
+    private evaluate;
+    /**
+     * Determine decision tier based on governance result
+     */
+    private determineTier;
+    /**
+     * Generate refinement options for YELLOW decisions
+     */
+    private generateRefinementOptions;
+    /**
+     * Check if a RED decision is a hard denial
+     */
+    private isHardDenial;
+    /**
+     * Extract violated policies from result
+     */
+    private extractViolatedPolicies;
+    /**
+     * Submit a refinement for a YELLOW decision
+     */
+    refine(refinementRequest: RefinementRequest): Promise<{
+        success: boolean;
+        decision: FluidDecision;
+        remainingAttempts: number;
+    }>;
+    /**
+     * Request human review for a YELLOW decision
+     */
+    requestReview(workflowId: string, reason: string): Promise<void>;
+    /**
+     * Approve a workflow (for human review)
+     */
+    approve(workflowId: string, approver: string, reason: string): Promise<void>;
+    /**
+     * Deny a workflow (for human review)
+     */
+    deny(workflowId: string, approver: string, reason: string): Promise<void>;
+    /**
+     * Start execution of an approved workflow
+     */
+    startExecution(workflowId: string): Promise<void>;
+    /**
+     * Complete a workflow
+     */
+    complete(workflowId: string): Promise<void>;
+    /**
+     * Mark a workflow as failed
+     */
+    fail(workflowId: string, error: string): Promise<void>;
+    /**
+     * Cancel a workflow
+     */
+    cancel(workflowId: string, reason: string): Promise<void>;
+    /**
+     * Get a workflow by ID
+     */
+    get(workflowId: string): WorkflowInstance | undefined;
+    /**
+     * Get all workflows for an agent
+     */
+    getByAgent(agentId: ID): WorkflowInstance[];
+    /**
+     * Transition a workflow to a new state
+     */
+    private transition;
+    /**
+     * Check for expired workflows and transition them
+     */
+    expireStaleWorkflows(): number;
+    /**
+     * Get workflow statistics
+     */
+    getStats(): {
+        total: number;
+        byState: Record<WorkflowState, number>;
+        avgDecisionsPerWorkflow: number;
+    };
+}
+/**
+ * Create a new fluid workflow engine
+ */
+export declare function createFluidWorkflowEngine(governanceEngine: GovernanceEngine, config?: Partial<FluidWorkflowConfig>): FluidWorkflowEngine;
+//# sourceMappingURL=fluid-workflow.d.ts.map

package/dist/governance/fluid-workflow.d.ts.map

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