claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/guidance/dist/evolution.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Evolution Pipeline
+ *
+ * Every change to prompts, policies, tools, and code becomes a signed change
+ * proposal that goes through simulation, replay comparison, and staged rollout.
+ *
+ * Pipeline stages:
+ * 1. Propose - Create a signed ChangeProposal
+ * 2. Simulate - Replay golden traces with baseline vs candidate config
+ * 3. Compare  - Approve or reject based on divergence threshold
+ * 4. Stage    - Create a staged rollout plan (canary -> partial -> full)
+ * 5. Advance  - Progress through stages with metric gates
+ * 6. Promote / Rollback - Apply permanently or revert
+ *
+ * @module @claude-flow/guidance/evolution
+ */
+/**
+ * The kind of change being proposed.
+ */
+export type ChangeProposalKind = 'rule-modify' | 'rule-add' | 'rule-remove' | 'rule-promote' | 'policy-update' | 'tool-config' | 'budget-adjust';
+/**
+ * Lifecycle status of a change proposal.
+ */
+export type ProposalStatus = 'draft' | 'signed' | 'simulating' | 'compared' | 'staged' | 'promoted' | 'rolled-back' | 'rejected';
+/**
+ * Risk assessment attached to a proposal.
+ */
+export interface RiskAssessment {
+    level: 'low' | 'medium' | 'high';
+    factors: string[];
+}
+/**
+ * A signed change proposal describing a modification to the guidance system.
+ */
+export interface ChangeProposal {
+    /** Unique identifier (UUID) */
+    proposalId: string;
+    /** What kind of change this is */
+    kind: ChangeProposalKind;
+    /** Short human-readable title */
+    title: string;
+    /** Longer description of the change */
+    description: string;
+    /** Agent or human ID that authored the proposal */
+    author: string;
+    /** Dot-path or identifier of what is being changed */
+    targetPath: string;
+    /** Before/after snapshot of the change */
+    diff: {
+        before: unknown;
+        after: unknown;
+    };
+    /** Why this change is being proposed */
+    rationale: string;
+    /** Risk assessment for the change */
+    riskAssessment: RiskAssessment;
+    /** HMAC-SHA256 signature of the proposal content */
+    signature: string;
+    /** Epoch ms when the proposal was created */
+    createdAt: number;
+    /** Current lifecycle status */
+    status: ProposalStatus;
+}
+/**
+ * A single decision point where baseline and candidate diverged.
+ */
+export interface DecisionDiff {
+    /** Sequence number in the trace */
+    seq: number;
+    /** What the baseline decided */
+    baseline: unknown;
+    /** What the candidate decided */
+    candidate: unknown;
+    /** How severe the divergence is */
+    severity: 'low' | 'medium' | 'high';
+}
+/**
+ * Result of simulating a proposal against golden traces.
+ */
+export interface SimulationResult {
+    /** Proposal that was simulated */
+    proposalId: string;
+    /** Hash of the trace produced by baseline config */
+    baselineTraceHash: string;
+    /** Hash of the trace produced by candidate config */
+    candidateTraceHash: string;
+    /** 0-1 score: 0 = identical, 1 = completely different */
+    divergenceScore: number;
+    /** Individual decision points where behaviour diverged */
+    decisionDiffs: DecisionDiff[];
+    /** Side-by-side metric comparison */
+    metricsComparison: {
+        baseline: Record<string, number>;
+        candidate: Record<string, number>;
+    };
+    /** Whether the simulation passed acceptance criteria */
+    passed: boolean;
+    /** Human-readable reason for the verdict */
+    reason: string;
+}
+/**
+ * A single stage in a staged rollout.
+ */
+export interface RolloutStage {
+    /** Stage name (e.g. 'canary', 'partial', 'full') */
+    name: string;
+    /** Percentage of traffic/agents this stage covers (0-100) */
+    percentage: number;
+    /** How long this stage should run before advancing (ms) */
+    durationMs: number;
+    /** Observed metrics during this stage */
+    metrics: Record<string, number>;
+    /** Maximum acceptable divergence before auto-rollback */
+    divergenceThreshold: number;
+    /** null = not evaluated yet, true = passed, false = failed */
+    passed: boolean | null;
+    /** Epoch ms when the stage started (null if not started) */
+    startedAt: number | null;
+    /** Epoch ms when the stage completed (null if not completed) */
+    completedAt: number | null;
+}
+/**
+ * A staged rollout plan for a change proposal.
+ */
+export interface StagedRollout {
+    /** Unique rollout identifier */
+    rolloutId: string;
+    /** The proposal being rolled out */
+    proposalId: string;
+    /** Ordered stages (canary -> partial -> full) */
+    stages: RolloutStage[];
+    /** Index of the current stage (0-based) */
+    currentStage: number;
+    /** Overall rollout status */
+    status: 'in-progress' | 'completed' | 'rolled-back';
+    /** Epoch ms when the rollout started */
+    startedAt: number;
+    /** Epoch ms when the rollout completed (null if still running) */
+    completedAt: number | null;
+}
+/**
+ * History entry combining proposal, optional simulation, optional rollout,
+ * and final outcome.
+ */
+export interface EvolutionHistoryEntry {
+    proposal: ChangeProposal;
+    simulation?: SimulationResult;
+    rollout?: StagedRollout;
+    outcome: ProposalStatus;
+}
+/**
+ * Evaluator function for simulation: given a golden trace and a config variant,
+ * produce a trace hash and metrics.
+ */
+export type TraceEvaluator = (trace: unknown, config: 'baseline' | 'candidate') => {
+    traceHash: string;
+    metrics: Record<string, number>;
+    decisions: unknown[];
+};
+export interface EvolutionPipelineConfig {
+    /** HMAC signing key for proposals */
+    signingKey?: string;
+    /** Maximum divergence score (0-1) to approve a change */
+    maxDivergence?: number;
+    /** Default rollout stages */
+    stages?: RolloutStage[];
+}
+/**
+ * The Evolution Pipeline manages the lifecycle of change proposals through
+ * signing, simulation, comparison, staged rollout, and promotion or rollback.
+ */
+export declare class EvolutionPipeline {
+    private readonly signingKey;
+    private readonly maxDivergence;
+    private readonly defaultStages;
+    private proposals;
+    private simulations;
+    private rollouts;
+    constructor(config?: EvolutionPipelineConfig);
+    /**
+     * Create and sign a new change proposal.
+     */
+    propose(params: {
+        kind: ChangeProposalKind;
+        title: string;
+        description: string;
+        author: string;
+        targetPath: string;
+        diff: {
+            before: unknown;
+            after: unknown;
+        };
+        rationale: string;
+        riskAssessment: RiskAssessment;
+    }): ChangeProposal;
+    /**
+     * Run golden traces through both baseline and candidate configs to measure
+     * divergence. The evaluator is called once per golden trace per config.
+     */
+    simulate(proposalId: string, goldenTraces: unknown[], evaluator: TraceEvaluator): SimulationResult;
+    /**
+     * Compare a simulation result against acceptance criteria.
+     *
+     * Checks:
+     * 1. Divergence is below threshold
+     * 2. No regression in key metrics (candidate >= baseline)
+     */
+    compare(proposalId: string, simulationResult: SimulationResult): {
+        approved: boolean;
+        reason: string;
+    };
+    /**
+     * Create a staged rollout plan for a proposal.
+     */
+    stage(proposalId: string): StagedRollout;
+    /**
+     * Advance to the next rollout stage or auto-rollback.
+     *
+     * If `stageMetrics.divergence` exceeds the current stage's threshold,
+     * the rollout is automatically rolled back.
+     */
+    advanceStage(rolloutId: string, stageMetrics: Record<string, number>): {
+        advanced: boolean;
+        rolledBack: boolean;
+        reason: string;
+    };
+    /**
+     * Roll back a staged rollout.
+     */
+    rollback(rolloutId: string, reason: string): void;
+    /**
+     * Promote a rollout, permanently applying the change.
+     */
+    promote(rolloutId: string): void;
+    /**
+     * Get a proposal by ID.
+     */
+    getProposal(id: string): ChangeProposal | undefined;
+    /**
+     * Get all proposals, optionally filtered by status.
+     */
+    getProposals(status?: ProposalStatus): ChangeProposal[];
+    /**
+     * Get a rollout by ID.
+     */
+    getRollout(id: string): StagedRollout | undefined;
+    /**
+     * Get the full evolution history across all proposals.
+     */
+    getHistory(): EvolutionHistoryEntry[];
+    /**
+     * Produce an HMAC-SHA256 signature for a proposal.
+     *
+     * The signature covers every field except `signature` and `status`.
+     */
+    private signProposal;
+    /**
+     * Compute a composite hash from an array of trace hashes.
+     */
+    private hashTraceResults;
+    /**
+     * Classify how severe a single decision diff is.
+     */
+    private classifyDiffSeverity;
+    /**
+     * Compute an overall divergence score (0-1).
+     */
+    private computeDivergenceScore;
+    /**
+     * Aggregate an array of metric records into averages.
+     */
+    private aggregateMetrics;
+    /**
+     * Find the rollout associated with a proposal.
+     */
+    private findRolloutByProposal;
+}
+/**
+ * Create an EvolutionPipeline instance.
+ */
+export declare function createEvolutionPipeline(config?: EvolutionPipelineConfig): EvolutionPipeline;
+//# sourceMappingURL=evolution.d.ts.map