agentic-qe 3.8.10 → 3.8.12

package/dist/coordination/deterministic-actions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Deterministic Step Actions (Imp-9)
+ *
+ * Built-in actions that execute WITHOUT LLM tokens.  Each action maps to a
+ * domain + action pair and is automatically wired into the WorkflowOrchestrator
+ * as a fallback before domain service delegation.
+ *
+ * When the caller supplies explicit input values they are used directly.
+ * When inputs are omitted, the actions query the unified SQLite database
+ * for live metrics — keeping execution fully deterministic (SQL-only).
+ */
+import { Result, DomainName } from '../shared/types/index.js';
+import type { WorkflowContext } from './workflow-types.js';
+/**
+ * A deterministic action that runs without any LLM tokens.
+ */
+export interface DeterministicAction {
+    /** Unique action identifier */
+    id: string;
+    /** Target domain */
+    domain: DomainName;
+    /** Action name within the domain */
+    action: string;
+    /** Execute the action with the given input */
+    execute(input: Record<string, unknown>, context: WorkflowContext): Promise<Result<Record<string, unknown>, Error>>;
+}
+/**
+ * Look up a deterministic action by domain + action.
+ * Returns undefined if no built-in action matches.
+ */
+export declare function findDeterministicAction(domain: DomainName, action: string): DeterministicAction | undefined;
+/**
+ * Get all registered deterministic actions.
+ */
+export declare function getAllDeterministicActions(): readonly DeterministicAction[];
+//# sourceMappingURL=deterministic-actions.d.ts.map

package/dist/coordination/deterministic-actions.js

@@ -0,0 +1,257 @@
+/**
+ * Deterministic Step Actions (Imp-9)
+ *
+ * Built-in actions that execute WITHOUT LLM tokens.  Each action maps to a
+ * domain + action pair and is automatically wired into the WorkflowOrchestrator
+ * as a fallback before domain service delegation.
+ *
+ * When the caller supplies explicit input values they are used directly.
+ * When inputs are omitted, the actions query the unified SQLite database
+ * for live metrics — keeping execution fully deterministic (SQL-only).
+ */
+import { ok } from '../shared/types/index.js';
+function tryGetDb() {
+    try {
+        // Dynamic import to avoid hard dependency — the module may not be initialised
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { getUnifiedMemory } = require('../kernel/unified-memory.js');
+        const um = getUnifiedMemory();
+        if (!um.isInitialized())
+            return null;
+        return um.getDatabase();
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Quality Gate Check
+// ============================================================================
+const qualityGateCheck = {
+    id: 'quality-gate-check',
+    domain: 'quality-assessment',
+    action: 'gate-check',
+    async execute(input) {
+        const coverageMin = typeof input.coverageMin === 'number' ? input.coverageMin : 80;
+        const testsPassingMin = typeof input.testsPassingMin === 'number' ? input.testsPassingMin : 90;
+        const maxBugs = typeof input.maxBugs === 'number' ? input.maxBugs : 5;
+        // ----- Fetch live data from DB when not supplied by caller -----
+        let currentCoverage = typeof input.currentCoverage === 'number' ? input.currentCoverage : null;
+        let currentTestsPassingRate = typeof input.currentTestsPassingRate === 'number' ? input.currentTestsPassingRate : null;
+        let currentBugs = typeof input.currentBugs === 'number' ? input.currentBugs : null;
+        if (currentCoverage === null || currentTestsPassingRate === null || currentBugs === null) {
+            const db = tryGetDb();
+            if (db) {
+                try {
+                    // Latest coverage from coverage_sessions
+                    if (currentCoverage === null) {
+                        const row = db.prepare(`SELECT after_lines FROM coverage_sessions ORDER BY created_at DESC LIMIT 1`).get();
+                        currentCoverage = row?.after_lines ?? 0;
+                    }
+                    // Test pass rate from recent test_outcomes
+                    if (currentTestsPassingRate === null) {
+                        const row = db.prepare(`SELECT COUNT(*) as total,
+                      SUM(CASE WHEN passed = 1 THEN 1 ELSE 0 END) as passed
+               FROM test_outcomes
+               WHERE created_at > datetime('now', '-7 days')`).get();
+                        currentTestsPassingRate =
+                            row && row.total > 0 ? (row.passed / row.total) * 100 : 0;
+                    }
+                    // Bug count: failed non-flaky tests in the last 7 days
+                    if (currentBugs === null) {
+                        const row = db.prepare(`SELECT COUNT(*) as bugs FROM test_outcomes
+               WHERE passed = 0 AND flaky = 0
+               AND created_at > datetime('now', '-7 days')`).get();
+                        currentBugs = row?.bugs ?? 0;
+                    }
+                }
+                catch {
+                    // Graceful degradation — fall through to defaults
+                }
+            }
+        }
+        // Apply defaults for anything still null
+        currentCoverage = currentCoverage ?? 0;
+        currentTestsPassingRate = currentTestsPassingRate ?? 0;
+        currentBugs = currentBugs ?? 0;
+        const coveragePassed = currentCoverage >= coverageMin;
+        const testsPassed = currentTestsPassingRate >= testsPassingMin;
+        const bugsPassed = currentBugs <= maxBugs;
+        const passed = coveragePassed && testsPassed && bugsPassed;
+        // Score is a normalized 0-1 value
+        const coverageScore = Math.min(currentCoverage / coverageMin, 1);
+        const testsScore = Math.min(currentTestsPassingRate / testsPassingMin, 1);
+        const bugsScore = maxBugs > 0 ? Math.max(0, 1 - currentBugs / maxBugs) : (currentBugs === 0 ? 1 : 0);
+        const score = (coverageScore + testsScore + bugsScore) / 3;
+        return ok({
+            passed,
+            score: Math.round(score * 100) / 100,
+            source: typeof input.currentCoverage === 'number' ? 'input' : 'database',
+            details: {
+                coverage: { current: currentCoverage, threshold: coverageMin, passed: coveragePassed },
+                testsPassing: { current: currentTestsPassingRate, threshold: testsPassingMin, passed: testsPassed },
+                bugs: { current: currentBugs, threshold: maxBugs, passed: bugsPassed },
+            },
+        });
+    },
+};
+// ============================================================================
+// Coverage Threshold Check
+// ============================================================================
+const coverageThresholdCheck = {
+    id: 'coverage-threshold',
+    domain: 'coverage-analysis',
+    action: 'threshold-check',
+    async execute(input) {
+        const minCoverage = typeof input.minCoverage === 'number' ? input.minCoverage : 80;
+        // ----- Fetch from DB when not supplied -----
+        let currentCoverage = typeof input.currentCoverage === 'number' ? input.currentCoverage : null;
+        let source = 'input';
+        if (currentCoverage === null) {
+            source = 'database';
+            const db = tryGetDb();
+            if (db) {
+                try {
+                    const row = db.prepare(`SELECT after_lines FROM coverage_sessions ORDER BY created_at DESC LIMIT 1`).get();
+                    currentCoverage = row?.after_lines ?? 0;
+                }
+                catch {
+                    currentCoverage = 0;
+                }
+            }
+            else {
+                currentCoverage = 0;
+            }
+        }
+        const passed = currentCoverage >= minCoverage;
+        const gap = passed ? 0 : Math.round((minCoverage - currentCoverage) * 100) / 100;
+        return ok({
+            currentCoverage,
+            passed,
+            gap,
+            minCoverage,
+            source,
+        });
+    },
+};
+// ============================================================================
+// Pattern Health Check
+// ============================================================================
+const patternHealthCheck = {
+    id: 'pattern-health',
+    domain: 'learning-optimization',
+    action: 'health-check',
+    async execute(input) {
+        // ----- Fetch from DB when not supplied -----
+        let totalPatterns = typeof input.totalPatterns === 'number' ? input.totalPatterns : null;
+        let activePatterns = typeof input.activePatterns === 'number' ? input.activePatterns : null;
+        let avgConfidence = typeof input.avgConfidence === 'number' ? input.avgConfidence : null;
+        let source = 'input';
+        if (totalPatterns === null || activePatterns === null || avgConfidence === null) {
+            source = 'database';
+            const db = tryGetDb();
+            if (db) {
+                try {
+                    const row = db.prepare(`
+            SELECT COUNT(*) as total,
+                   SUM(CASE WHEN deprecated_at IS NULL AND confidence >= 0.3 THEN 1 ELSE 0 END) as active,
+                   AVG(confidence) as avg_conf
+            FROM qe_patterns
+          `).get();
+                    totalPatterns = totalPatterns ?? (row?.total ?? 0);
+                    activePatterns = activePatterns ?? (row?.active ?? 0);
+                    avgConfidence = avgConfidence ?? (row?.avg_conf ?? 0);
+                }
+                catch {
+                    // Graceful degradation
+                }
+            }
+        }
+        // Apply defaults for anything still null
+        totalPatterns = totalPatterns ?? 0;
+        activePatterns = activePatterns ?? 0;
+        avgConfidence = avgConfidence ?? 0;
+        // Health score: weighted combination of volume, activity ratio, and confidence
+        const volumeScore = Math.min(totalPatterns / 100, 1); // 100 patterns = max volume
+        const activityRatio = totalPatterns > 0 ? activePatterns / totalPatterns : 0;
+        const healthScore = Math.round((volumeScore * 0.3 + activityRatio * 0.3 + avgConfidence * 0.4) * 100) / 100;
+        return ok({
+            totalPatterns,
+            activePatterns,
+            avgConfidence,
+            healthScore,
+            source,
+        });
+    },
+};
+// ============================================================================
+// Routing Accuracy Check
+// ============================================================================
+const routingAccuracyCheck = {
+    id: 'routing-accuracy',
+    domain: 'learning-optimization',
+    action: 'routing-check',
+    async execute(input) {
+        // ----- Fetch from DB when not supplied -----
+        let totalOutcomes = typeof input.totalOutcomes === 'number' ? input.totalOutcomes : null;
+        let successfulOutcomes = typeof input.successfulOutcomes === 'number' ? input.successfulOutcomes : null;
+        let confidenceCorrelation = typeof input.confidenceCorrelation === 'number' ? input.confidenceCorrelation : null;
+        let source = 'input';
+        if (totalOutcomes === null || successfulOutcomes === null) {
+            source = 'database';
+            const db = tryGetDb();
+            if (db) {
+                try {
+                    const row = db.prepare(`
+            SELECT COUNT(*) as total,
+                   SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as successful
+            FROM routing_outcomes
+          `).get();
+                    totalOutcomes = totalOutcomes ?? (row?.total ?? 0);
+                    successfulOutcomes = successfulOutcomes ?? (row?.successful ?? 0);
+                }
+                catch {
+                    // Graceful degradation
+                }
+            }
+        }
+        // Apply defaults
+        totalOutcomes = totalOutcomes ?? 0;
+        successfulOutcomes = successfulOutcomes ?? 0;
+        confidenceCorrelation = confidenceCorrelation ?? 0;
+        const successRate = totalOutcomes > 0
+            ? Math.round((successfulOutcomes / totalOutcomes) * 10000) / 100
+            : 0;
+        return ok({
+            successRate,
+            totalOutcomes,
+            successfulOutcomes,
+            confidenceCorrelation,
+            source,
+        });
+    },
+};
+// ============================================================================
+// Registry
+// ============================================================================
+/** All built-in deterministic actions */
+const DETERMINISTIC_ACTIONS = [
+    qualityGateCheck,
+    coverageThresholdCheck,
+    patternHealthCheck,
+    routingAccuracyCheck,
+];
+/**
+ * Look up a deterministic action by domain + action.
+ * Returns undefined if no built-in action matches.
+ */
+export function findDeterministicAction(domain, action) {
+    return DETERMINISTIC_ACTIONS.find((a) => a.domain === domain && a.action === action);
+}
+/**
+ * Get all registered deterministic actions.
+ */
+export function getAllDeterministicActions() {
+    return DETERMINISTIC_ACTIONS;
+}
+//# sourceMappingURL=deterministic-actions.js.map

package/dist/coordination/workflow-orchestrator.d.ts

@@ -10,7 +10,7 @@
 import { Result, DomainName } from '../shared/types/index.js';
 import { EventBus, MemoryBackend, AgentCoordinator } from '../kernel/interfaces.js';
 import type { BehaviorNode } from './behavior-tree/nodes.js';
-export type { StepExecutionMode, StepStatus, WorkflowStatus, ConditionOperator, StepCondition, WorkflowStepDefinition, WorkflowDefinition, WorkflowTrigger, StepExecutionResult, WorkflowContext, WorkflowExecutionStatus, WorkflowListItem, WorkflowStartedPayload, WorkflowCompletedPayload, WorkflowFailedPayload, StepEventPayload, IWorkflowOrchestrator, DomainAction, DomainActionRegistry, WorkflowOrchestratorConfig, } from './workflow-types.js';
+export type { StepExecutionMode, StepStatus, WorkflowStatus, ConditionOperator, StepCondition, WorkflowStepDefinition, WorkflowDefinition, WorkflowTrigger, StepExecutionResult, WorkflowContext, WorkflowExecutionStatus, WorkflowListItem, WorkflowStartedPayload, WorkflowCompletedPayload, WorkflowFailedPayload, StepEventPayload, StepAwaitingApprovalPayload, IWorkflowOrchestrator, DomainAction, DomainActionRegistry, WorkflowOrchestratorConfig, } from './workflow-types.js';
 export { WorkflowEvents, DEFAULT_WORKFLOW_CONFIG, } from './workflow-types.js';
 import type { WorkflowDefinition, WorkflowExecutionStatus, WorkflowListItem, IWorkflowOrchestrator, DomainAction, WorkflowOrchestratorConfig } from './workflow-types.js';
 export declare class WorkflowOrchestrator implements IWorkflowOrchestrator {
@@ -22,6 +22,8 @@ export declare class WorkflowOrchestrator implements IWorkflowOrchestrator {
     private readonly executions;
     private readonly actionRegistry;
     private readonly eventSubscriptions;
+    /** Pending approval gates: Map<`${executionId}:${stepId}`, gate> */
+    private readonly approvalGates;
     private initialized;
     constructor(eventBus: EventBus, memory: MemoryBackend, agentCoordinator: AgentCoordinator, config?: Partial<WorkflowOrchestratorConfig>);
     initialize(): Promise<void>;
@@ -36,6 +38,16 @@ export declare class WorkflowOrchestrator implements IWorkflowOrchestrator {
     listWorkflows(): WorkflowListItem[];
     getActiveExecutions(): WorkflowExecutionStatus[];
     getWorkflow(workflowId: string): WorkflowDefinition | undefined;
+    /**
+     * Approve a step that is awaiting approval. Returns true if the step
+     * was found and approved, false otherwise.
+     */
+    approveStep(executionId: string, stepId: string): boolean;
+    /**
+     * Reject a step that is awaiting approval. Returns true if the step
+     * was found and rejected, false otherwise.
+     */
+    rejectStep(executionId: string, stepId: string, reason?: string): boolean;
     isActionRegistered(domain: DomainName, action: string): boolean;
     getRegisteredActions(domain: DomainName): string[];
     getDomainsWithActions(): DomainName[];
@@ -81,6 +93,11 @@ export declare class WorkflowOrchestrator implements IWorkflowOrchestrator {
     private loadPersistedWorkflows;
     private persistWorkflows;
     private persistExecution;
+    /**
+     * Wait for external approval (or auto-approve after timeout).
+     * Returns an object with approved status and optional rejection reason.
+     */
+    private waitForApproval;
     private delay;
 }
 export declare function createWorkflowOrchestrator(eventBus: EventBus, memory: MemoryBackend, agentCoordinator: AgentCoordinator, config?: Partial<WorkflowOrchestratorConfig>): IWorkflowOrchestrator;

package/dist/coordination/workflow-orchestrator.js

@@ -13,6 +13,8 @@ import { createEvent } from '../shared/events/domain-events.js';
 import { toError, toErrorMessage } from '../shared/error-utils.js';
 export { WorkflowEvents, DEFAULT_WORKFLOW_CONFIG, } from './workflow-types.js';
 import { WorkflowEvents, DEFAULT_WORKFLOW_CONFIG } from './workflow-types.js';
+// Import deterministic actions
+import { findDeterministicAction } from './deterministic-actions.js';
 // Import built-in workflows
 import { getBuiltInWorkflows, BUILTIN_WORKFLOW_IDS } from './workflow-builtin.js';
 // ============================================================================
@@ -27,6 +29,8 @@ export class WorkflowOrchestrator {
     executions = new Map();
     actionRegistry = {};
     eventSubscriptions = [];
+    /** Pending approval gates: Map<`${executionId}:${stepId}`, gate> */
+    approvalGates = new Map();
     initialized = false;
     constructor(eventBus, memory, agentCoordinator, config = {}) {
         this.eventBus = eventBus;
@@ -127,6 +131,13 @@ export class WorkflowOrchestrator {
         execution.status = 'cancelled';
         execution.completedAt = new Date();
         execution.duration = execution.completedAt.getTime() - execution.startedAt.getTime();
+        // Clean up any pending approval gates for this execution to prevent timer leaks
+        for (const [key, gate] of this.approvalGates.entries()) {
+            if (key.startsWith(`${executionId}:`)) {
+                gate.resolve({ approved: false, reason: 'Workflow cancelled' });
+                this.approvalGates.delete(key);
+            }
+        }
         await this.publishEvent(WorkflowEvents.WorkflowCancelled, {
             executionId, workflowId: execution.workflowId, workflowName: execution.workflowName,
         }, execution.context.metadata.correlationId);
@@ -171,6 +182,35 @@ export class WorkflowOrchestrator {
         return this.workflows.get(workflowId);
     }
     // ============================================================================
+    // Approval Gate Methods
+    // ============================================================================
+    /**
+     * Approve a step that is awaiting approval. Returns true if the step
+     * was found and approved, false otherwise.
+     */
+    approveStep(executionId, stepId) {
+        const key = `${executionId}:${stepId}`;
+        const gate = this.approvalGates.get(key);
+        if (!gate)
+            return false;
+        gate.resolve({ approved: true });
+        this.approvalGates.delete(key);
+        return true;
+    }
+    /**
+     * Reject a step that is awaiting approval. Returns true if the step
+     * was found and rejected, false otherwise.
+     */
+    rejectStep(executionId, stepId, reason) {
+        const key = `${executionId}:${stepId}`;
+        const gate = this.approvalGates.get(key);
+        if (!gate)
+            return false;
+        gate.resolve({ approved: false, reason });
+        this.approvalGates.delete(key);
+        return true;
+    }
+    // ============================================================================
     // Public Utility Methods
     // ============================================================================
     isActionRegistered(domain, action) {
@@ -402,6 +442,20 @@ export class WorkflowOrchestrator {
                     const stepTimeout = step.timeout || this.config.defaultStepTimeout;
                     const output = await this.executeStepAction(step, input, execution.context, stepTimeout);
                     this.mapStepOutput(step, output, execution.context);
+                    // Handle approval gate if configured
+                    if (step.approval) {
+                        const approvalResult = await this.waitForApproval(step, execution);
+                        if (!approvalResult.approved) {
+                            result.status = 'failed';
+                            result.error = approvalResult.reason || 'Step rejected at approval gate';
+                            result.output = output;
+                            result.completedAt = new Date();
+                            result.duration = result.completedAt.getTime() - startedAt.getTime();
+                            execution.stepResults.set(step.id, result);
+                            await this.publishStepFailed(execution, step, result.error);
+                            return result;
+                        }
+                    }
                     result.status = 'completed';
                     result.output = output;
                     result.completedAt = new Date();
@@ -439,11 +493,20 @@ export class WorkflowOrchestrator {
         }
     }
     async executeStepAction(step, input, context, timeout) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(`Step timeout after ${timeout}ms`)), timeout);
+        });
+        // Check for a deterministic action first (zero LLM tokens)
+        const deterministicAction = findDeterministicAction(step.domain, step.action);
+        if (deterministicAction) {
+            const actionResult = await Promise.race([deterministicAction.execute(input, context), timeoutPromise]);
+            if (!actionResult.success)
+                throw actionResult.error;
+            return actionResult.value;
+        }
+        // Fall back to registered domain actions
         const domainActions = this.actionRegistry[step.domain];
         if (domainActions?.[step.action]) {
-            const timeoutPromise = new Promise((_, reject) => {
-                setTimeout(() => reject(new Error(`Step timeout after ${timeout}ms`)), timeout);
-            });
             const actionResult = await Promise.race([domainActions[step.action](input, context), timeoutPromise]);
             if (!actionResult.success)
                 throw actionResult.error;
@@ -751,6 +814,53 @@ export class WorkflowOrchestrator {
         }
     }
     // ============================================================================
+    // Private Methods - Approval Gates
+    // ============================================================================
+    /**
+     * Wait for external approval (or auto-approve after timeout).
+     * Returns an object with approved status and optional rejection reason.
+     */
+    async waitForApproval(step, execution) {
+        const approvalConfig = typeof step.approval === 'object' ? step.approval : {};
+        const autoApproveAfter = approvalConfig.autoApproveAfter ?? 300000; // 5 min default
+        const message = approvalConfig.message ?? `Awaiting approval for step: ${step.name}`;
+        // Update step result status
+        const stepResult = execution.stepResults.get(step.id);
+        if (stepResult)
+            stepResult.status = 'awaiting_approval';
+        // Emit StepAwaitingApproval event
+        await this.publishEvent(WorkflowEvents.StepAwaitingApproval, {
+            executionId: execution.executionId,
+            workflowId: execution.workflowId,
+            stepId: step.id,
+            stepName: step.name,
+            domain: step.domain,
+            message,
+            autoApproveAfter: autoApproveAfter > 0 ? autoApproveAfter : undefined,
+        }, execution.context.metadata.correlationId);
+        const key = `${execution.executionId}:${step.id}`;
+        return new Promise((resolve) => {
+            // Store the gate so approveStep/rejectStep can resolve it
+            const gate = { resolve };
+            this.approvalGates.set(key, gate);
+            // Auto-approve timer (0 = never auto-approve)
+            if (autoApproveAfter > 0) {
+                const timer = setTimeout(() => {
+                    if (this.approvalGates.has(key)) {
+                        this.approvalGates.delete(key);
+                        resolve({ approved: true }); // auto-approve on timeout
+                    }
+                }, autoApproveAfter);
+                // Wrap resolve to also clear the timer
+                const originalResolve = gate.resolve;
+                gate.resolve = (result) => {
+                    clearTimeout(timer);
+                    originalResolve(result);
+                };
+            }
+        });
+    }
+    // ============================================================================
     // Private Methods - Utilities
     // ============================================================================
     delay(ms) {

package/dist/coordination/workflow-types.d.ts

@@ -12,7 +12,7 @@ export type StepExecutionMode = 'sequential' | 'parallel';
 /**
  * Step status
  */
-export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+export type StepStatus = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'awaiting_approval';
 /**
  * Workflow status
  */
@@ -70,6 +70,13 @@ export interface WorkflowStepDefinition {
     };
     /** Continue workflow on failure */
     continueOnFailure?: boolean;
+    /** Approval gate configuration */
+    approval?: boolean | {
+        /** Auto-approve after this many ms (0 = never auto-approve) */
+        autoApproveAfter?: number;
+        /** Approval prompt message */
+        message?: string;
+    };
 }
 /**
  * Workflow definition
@@ -178,6 +185,9 @@ export declare const WorkflowEvents: {
     readonly StepCompleted: "workflow.StepCompleted";
     readonly StepFailed: "workflow.StepFailed";
     readonly StepSkipped: "workflow.StepSkipped";
+    readonly StepAwaitingApproval: "workflow.StepAwaitingApproval";
+    readonly StepApproved: "workflow.StepApproved";
+    readonly StepRejected: "workflow.StepRejected";
 };
 export interface WorkflowStartedPayload {
     executionId: string;
@@ -207,6 +217,10 @@ export interface StepEventPayload {
     stepName: string;
     domain: DomainName;
 }
+export interface StepAwaitingApprovalPayload extends StepEventPayload {
+    message?: string;
+    autoApproveAfter?: number;
+}
 export interface IWorkflowOrchestrator {
     /** Initialize the orchestrator */
     initialize(): Promise<void>;
@@ -232,6 +246,10 @@ export interface IWorkflowOrchestrator {
     getActiveExecutions(): WorkflowExecutionStatus[];
     /** Get workflow definition */
     getWorkflow(workflowId: string): WorkflowDefinition | undefined;
+    /** Approve a step that is awaiting approval */
+    approveStep(executionId: string, stepId: string): boolean;
+    /** Reject a step that is awaiting approval */
+    rejectStep(executionId: string, stepId: string, reason?: string): boolean;
 }
 export type DomainAction = (input: Record<string, unknown>, context: WorkflowContext) => Promise<Result<unknown, Error>>;
 export interface DomainActionRegistry {

package/dist/coordination/workflow-types.js

@@ -16,6 +16,9 @@ export const WorkflowEvents = {
     StepCompleted: 'workflow.StepCompleted',
     StepFailed: 'workflow.StepFailed',
     StepSkipped: 'workflow.StepSkipped',
+    StepAwaitingApproval: 'workflow.StepAwaitingApproval',
+    StepApproved: 'workflow.StepApproved',
+    StepRejected: 'workflow.StepRejected',
 };
 export const DEFAULT_WORKFLOW_CONFIG = {
     maxConcurrentWorkflows: 10,

package/dist/coordination/yaml-pipeline-loader.d.ts

@@ -22,6 +22,7 @@ export declare class YamlPipelineLoader {
     private validateTriggers;
     private validateRetry;
     private validateRollback;
+    private validateApproval;
     /** Validate that a value is Record<string, string>, undefined, or return an Error. */
     private validateStringRecord;
     /** Resolve a dot-path variable (e.g. "foo.bar") from a variables map. */

package/dist/coordination/yaml-pipeline-loader.js

@@ -211,6 +211,14 @@ export class YamlPipelineLoader {
             const continueOnFailure = typeof s.continueOnFailure === 'boolean'
                 ? s.continueOnFailure
                 : undefined;
+            // Validate approval gate configuration
+            let approval;
+            if (s.approval !== undefined) {
+                const approvalResult = this.validateApproval(s.approval, s.id);
+                if (!approvalResult.success)
+                    return approvalResult;
+                approval = approvalResult.value;
+            }
             const step = {
                 id: s.id,
                 name: s.name,
@@ -225,6 +233,7 @@ export class YamlPipelineLoader {
                 ...(retry !== undefined && { retry }),
                 ...(rollback !== undefined && { rollback }),
                 ...(continueOnFailure !== undefined && { continueOnFailure }),
+                ...(approval !== undefined && { approval }),
             };
             steps.push(step);
         }
@@ -325,6 +334,31 @@ export class YamlPipelineLoader {
             ...(r.input !== undefined && typeof r.input === 'object' && { input: r.input }),
         });
     }
+    validateApproval(raw, stepId) {
+        // Simple boolean form: approval: true
+        if (typeof raw === 'boolean') {
+            return ok(raw);
+        }
+        // Object form: approval: { autoApproveAfter, message }
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return err(new Error(`Step '${stepId}': 'approval' must be a boolean or object`));
+        }
+        const a = raw;
+        const result = {};
+        if (a.autoApproveAfter !== undefined) {
+            if (typeof a.autoApproveAfter !== 'number' || a.autoApproveAfter < 0) {
+                return err(new Error(`Step '${stepId}': approval.autoApproveAfter must be a non-negative number`));
+            }
+            result.autoApproveAfter = a.autoApproveAfter;
+        }
+        if (a.message !== undefined) {
+            if (typeof a.message !== 'string') {
+                return err(new Error(`Step '${stepId}': approval.message must be a string`));
+            }
+            result.message = a.message;
+        }
+        return ok(result);
+    }
     /** Validate that a value is Record<string, string>, undefined, or return an Error. */
     validateStringRecord(value, label) {
         if (value === undefined || value === null)

package/dist/domains/code-intelligence/coordinator-gnn.d.ts

@@ -12,6 +12,13 @@ export declare function initializeGNNIndex(domainKey: string): QEGNNEmbeddingInd
  * Index code embeddings in GNN for fast similarity search
  */
 export declare function indexCodeEmbeddings(gnnIndex: QEGNNEmbeddingIndex, fileReader: FileReader, paths: string[]): Promise<void>;
+/**
+ * R4: Generate graph-aware embeddings for a set of files using GraphMAE.
+ * Builds a dependency graph from import relationships and uses masked
+ * autoencoders to produce structure-aware embeddings.
+ * Falls back to feature-hash embeddings when GraphMAE is disabled.
+ */
+export declare function generateGraphMAEEmbeddings(fileReader: FileReader, paths: string[]): Promise<Map<string, number[]>>;
 /**
  * Generate code embedding using semantic features
  */
@@ -34,6 +41,20 @@ export declare function mergeSearchResults(semanticResults: SearchResult[], gnnR
     file: string;
     similarity: number;
 }>): SearchResult[];
+/**
+ * R6: Train GNN embeddings with memory-bounded cold-tier training.
+ * Uses LRU hotset caching when the graph exceeds hotsetSize, falling
+ * back to full in-memory training for small graphs.
+ */
+export declare function trainWithColdTier(nodeFeatures: Map<number, Float32Array>, adjacency: Map<number, number[]>, options?: {
+    hotsetSize?: number;
+    epochs?: number;
+    hiddenDim?: number;
+}): {
+    embeddings: Map<number, Float32Array>;
+    loss: number;
+    usedColdTier: boolean;
+};
 /**
  * Simple hash function for strings
  */