moflo 4.8.31 → 4.8.32

package/src/@claude-flow/guidance/dist/meta-governance.d.ts

@@ -1,265 +0,0 @@
-/**
- * @fileoverview Meta-Governance Module
- *
- * Provides constitutional governance over the governance system itself.
- * Manages invariants, amendments, and optimizer constraints to prevent
- * governance drift and ensure constitutional stability.
- *
- * Features:
- * - Constitutional invariants with severity levels
- * - Amendment proposal and voting system
- * - Optimizer action validation
- * - Rate limiting and supermajority requirements
- * - Built-in constitutional protections
- *
- * Core capabilities:
- * - Constitutional invariant checking
- * - Amendment lifecycle (propose → vote → resolve → enact)
- * - Optimizer constraint enforcement
- * - Supermajority voting
- * - Emergency veto power
- * - Immutability protection
- *
- * @module @claude-flow/guidance/meta-governance
- * @author Claude Flow Team
- */
-/**
- * Result of checking a constitutional invariant
- */
-export interface InvariantCheckResult {
-    /** Whether the invariant holds */
-    holds: boolean;
-    /** Description of violation if invariant does not hold */
-    violation?: string;
-    /** Additional details about the check */
-    details?: Record<string, unknown>;
-}
-/**
- * Current state of the governance system for invariant checking
- */
-export interface GovernanceState {
-    /** Number of active governance rules */
-    ruleCount: number;
-    /** Size of constitution in lines */
-    constitutionSize: number;
-    /** Number of active gates */
-    gateCount: number;
-    /** Whether optimizer is enabled */
-    optimizerEnabled: boolean;
-    /** Number of active agents */
-    activeAgentCount: number;
-    /** Timestamp of last amendment */
-    lastAmendmentTimestamp: number;
-    /** Additional state metadata */
-    metadata: Record<string, unknown>;
-}
-/**
- * Constitutional invariant that must hold
- */
-export interface ConstitutionalInvariant {
-    /** Unique identifier */
-    id: string;
-    /** Human-readable name */
-    name: string;
-    /** Description of the invariant */
-    description: string;
-    /** Function to check if invariant holds */
-    check: (state: GovernanceState) => InvariantCheckResult;
-    /** Severity level */
-    severity: 'critical' | 'warning';
-    /** Whether this invariant can be removed */
-    immutable: boolean;
-}
-/**
- * A specific change within an amendment
- */
-export interface AmendmentChange {
-    /** Type of change */
-    type: 'add-rule' | 'remove-rule' | 'modify-rule' | 'adjust-threshold' | 'add-gate' | 'remove-gate';
-    /** Target of the change (rule ID, gate ID, etc.) */
-    target: string;
-    /** State before the change (for modify operations) */
-    before?: string;
-    /** State after the change */
-    after?: string;
-}
-/**
- * Amendment to the governance system
- */
-export interface Amendment {
-    /** Unique identifier */
-    id: string;
-    /** Agent or entity that proposed the amendment */
-    proposedBy: string;
-    /** Description of the amendment */
-    description: string;
-    /** Specific changes in the amendment */
-    changes: AmendmentChange[];
-    /** When the amendment was proposed */
-    timestamp: number;
-    /** Current status */
-    status: 'proposed' | 'approved' | 'rejected' | 'enacted' | 'vetoed';
-    /** Votes for/against (voterId → approve) */
-    votes: Map<string, boolean>;
-    /** Number of approvals required to pass */
-    requiredApprovals: number;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Constraints on optimizer behavior
- */
-export interface OptimizerConstraint {
-    /** Unique identifier */
-    id: string;
-    /** Human-readable name */
-    name: string;
-    /** Description of the constraint */
-    description: string;
-    /** Maximum governance drift per optimization cycle (0-1) */
-    maxDriftPerCycle: number;
-    /** Maximum rules promoted per cycle */
-    maxPromotionRate: number;
-    /** Maximum rules demoted per cycle */
-    maxDemotionRate: number;
-    /** Cooldown between optimizer actions (ms) */
-    cooldownMs: number;
-}
-/**
- * Action the optimizer wants to take
- */
-export interface OptimizerAction {
-    /** Type of action */
-    type: 'promote' | 'demote' | 'add' | 'remove' | 'reweight';
-    /** Target rule identifier */
-    targetRuleId: string;
-    /** Magnitude of the action (interpretation depends on type) */
-    magnitude: number;
-    /** When the action was requested */
-    timestamp: number;
-}
-/**
- * Validation result for an optimizer action
- */
-export interface OptimizerValidation {
-    /** Whether the action is allowed */
-    allowed: boolean;
-    /** Reason for the decision */
-    reason: string;
-    /** Specific constraint violations */
-    constraintViolations: string[];
-}
-/**
- * Report of all invariant checks
- */
-export interface InvariantReport {
-    /** Whether all invariants hold */
-    allHold: boolean;
-    /** Results for each invariant */
-    results: Array<{
-        invariant: ConstitutionalInvariant;
-        result: InvariantCheckResult;
-    }>;
-    /** When the report was generated */
-    timestamp: number;
-}
-/**
- * Configuration for meta-governance
- */
-export interface MetaGovernanceConfig {
-    /** Threshold for supermajority (0-1, default 0.75) */
-    supermajorityThreshold?: number;
-    /** Maximum amendments allowed per time window */
-    maxAmendmentsPerWindow?: number;
-    /** Time window for amendment rate limiting (ms) */
-    amendmentWindowMs?: number;
-    /** Optimizer constraints (partial allows overriding defaults) */
-    optimizerConstraints?: Partial<OptimizerConstraint>;
-    /** Optional signing key for amendments */
-    signingKey?: string;
-}
-/**
- * Meta-Governor: Governs the governance system itself
- *
- * Enforces constitutional invariants, manages amendments,
- * and constrains optimizer behavior to prevent governance drift.
- */
-export declare class MetaGovernor {
-    private invariants;
-    private amendments;
-    private amendmentHistory;
-    private optimizerConstraints;
-    private lastOptimizerAction;
-    private optimizerActionsThisCycle;
-    private readonly supermajorityThreshold;
-    private readonly maxAmendmentsPerWindow;
-    private readonly amendmentWindowMs;
-    private readonly signingKey?;
-    constructor(config?: MetaGovernanceConfig);
-    /**
-     * Add built-in constitutional invariants
-     */
-    private addBuiltInInvariants;
-    /**
-     * Add a constitutional invariant
-     */
-    addInvariant(invariant: ConstitutionalInvariant): void;
-    /**
-     * Remove an invariant (only if not immutable)
-     */
-    removeInvariant(id: string): boolean;
-    /**
-     * Check all constitutional invariants against current state
-     */
-    checkAllInvariants(state: GovernanceState): InvariantReport;
-    /**
-     * Propose a new amendment
-     */
-    proposeAmendment(proposal: Omit<Amendment, 'id' | 'timestamp' | 'status' | 'votes'>): Amendment;
-    /**
-     * Vote on an amendment
-     */
-    voteOnAmendment(amendmentId: string, voterId: string, approve: boolean): void;
-    /**
-     * Resolve an amendment (check if supermajority reached)
-     */
-    resolveAmendment(amendmentId: string): Amendment;
-    /**
-     * Enact an approved amendment
-     * Returns true if enacted successfully
-     */
-    enactAmendment(amendmentId: string): boolean;
-    /**
-     * Emergency veto of an amendment
-     */
-    vetoAmendment(amendmentId: string, reason: string): void;
-    /**
-     * Get full amendment history
-     */
-    getAmendmentHistory(): Amendment[];
-    /**
-     * Validate an optimizer action against constraints
-     */
-    validateOptimizerAction(action: OptimizerAction): OptimizerValidation;
-    /**
-     * Get current optimizer constraints
-     */
-    getConstraints(): OptimizerConstraint;
-    /**
-     * Reset optimizer action tracking (call at cycle boundaries)
-     */
-    resetOptimizerTracking(): void;
-    /**
-     * Get all invariants
-     */
-    getInvariants(): ConstitutionalInvariant[];
-    /**
-     * Get pending amendments
-     */
-    getPendingAmendments(): Amendment[];
-}
-/**
- * Factory function to create a MetaGovernor instance
- */
-export declare function createMetaGovernor(config?: MetaGovernanceConfig): MetaGovernor;
-//# sourceMappingURL=meta-governance.d.ts.map

package/src/@claude-flow/guidance/dist/optimizer.d.ts

@@ -1,104 +0,0 @@
-/**
- * Optimizer Loop
- *
- * Weekly loop that edits guidance like code:
- * 1. Rank top violations by frequency and cost
- * 2. For the top 3, propose one rule change each
- * 3. Run the fixed task suite with and without the change
- * 4. Promote only if risk does not increase and rework decreases
- * 5. Record the decision in an ADR note
- *
- * Promotion rule: Local rules that win twice become root rules.
- *
- * @module @claude-flow/guidance/optimizer
- */
-import type { PolicyBundle, ViolationRanking, RuleChange, ABTestResult, OptimizationMetrics, RuleADR } from './types.js';
-import type { RunLedger } from './ledger.js';
-export interface OptimizerConfig {
-    /** Number of top violations to address per cycle */
-    topViolationsPerCycle: number;
-    /** Minimum events required before optimization */
-    minEventsForOptimization: number;
-    /** Required improvement threshold for promotion (0-1) */
-    improvementThreshold: number;
-    /** Maximum risk increase tolerance (0-1) */
-    maxRiskIncrease: number;
-    /** Number of consecutive wins needed for promotion to root */
-    promotionWins: number;
-    /** ADR storage path */
-    adrPath: string;
-}
-export declare class OptimizerLoop {
-    private config;
-    private proposedChanges;
-    private testResults;
-    private adrs;
-    private promotionTracker;
-    private lastOptimizationRun;
-    constructor(config?: Partial<OptimizerConfig>);
-    /**
-     * Run a full optimization cycle
-     *
-     * Steps:
-     * 1. Rank violations
-     * 2. Propose changes for top N
-     * 3. Evaluate changes against baseline
-     * 4. Promote winners, record ADRs
-     */
-    runCycle(ledger: RunLedger, currentBundle: PolicyBundle): Promise<{
-        rankings: ViolationRanking[];
-        changes: RuleChange[];
-        results: ABTestResult[];
-        adrs: RuleADR[];
-        promoted: string[];
-        demoted: string[];
-    }>;
-    /**
-     * Propose rule changes for top violations
-     */
-    proposeChanges(violations: ViolationRanking[], bundle: PolicyBundle): RuleChange[];
-    /**
-     * Propose modification to an existing rule
-     */
-    private proposeRuleModification;
-    /**
-     * Propose a new rule for unhandled violations
-     */
-    private proposeNewRule;
-    /**
-     * Evaluate a proposed change against baseline metrics
-     */
-    evaluateChange(change: RuleChange, baseline: OptimizationMetrics, ledger: RunLedger): ABTestResult;
-    /**
-     * Heuristic estimation of how a rule change would affect metrics.
-     *
-     * This does NOT run a real A/B test against live traffic — it applies
-     * fixed multipliers per change-type to the baseline numbers.  The
-     * percentages (e.g. 40% for modify, 60% for add) are conservative
-     * estimates, not measured values.  Results should be treated as
-     * directional guidance, not ground truth.
-     */
-    private simulateChangeEffect;
-    /**
-     * Record an ADR for a rule change decision
-     */
-    private recordADR;
-    /**
-     * Find a rule in the policy bundle
-     */
-    private findRule;
-    /**
-     * Apply promoted changes to a policy bundle
-     */
-    applyPromotions(bundle: PolicyBundle, promoted: string[], changes: RuleChange[]): PolicyBundle;
-    get lastRun(): number | null;
-    getADRs(): RuleADR[];
-    getProposedChanges(): RuleChange[];
-    getTestResults(): ABTestResult[];
-    getPromotionTracker(): Map<string, number>;
-}
-/**
- * Create an optimizer instance
- */
-export declare function createOptimizer(config?: Partial<OptimizerConfig>): OptimizerLoop;
-//# sourceMappingURL=optimizer.d.ts.map

package/src/@claude-flow/guidance/dist/persistence.d.ts

@@ -1,189 +0,0 @@
-/**
- * Ledger Persistence Layer
- *
- * Connects the in-memory RunLedger to durable file-based storage using
- * newline-delimited JSON (NDJSON). Provides append-only event logging,
- * compaction, and lock-based concurrent access prevention.
- *
- * Storage layout:
- *   {storagePath}/events.ndjson  - Newline-delimited JSON events
- *   {storagePath}/index.json     - Metadata index (counts, timestamps, task IDs)
- *   {storagePath}/.lock          - Lock file for concurrent access prevention
- *
- * @module @claude-flow/guidance/persistence
- */
-import { RunLedger } from './ledger.js';
-import type { RunEvent } from './types.js';
-/**
- * Configuration for the persistent ledger
- */
-export interface PersistenceConfig {
-    /** Directory path for storage files (default: '.claude-flow/guidance') */
-    storagePath: string;
-    /** Maximum events to keep; oldest evicted on compact (default: 10000) */
-    maxEvents: number;
-    /** How often to compact/vacuum in milliseconds (default: 1 hour) */
-    compactIntervalMs: number;
-    /** Enable write-ahead logging style (flush after each write) (default: true) */
-    enableWAL: boolean;
-}
-/**
- * Storage statistics
- */
-export interface StorageStats {
-    /** Total number of stored events */
-    eventCount: number;
-    /** Storage size in bytes */
-    storageSizeBytes: number;
-    /** Timestamp of the oldest event (null if empty) */
-    oldestEvent: number | null;
-    /** Timestamp of the newest event (null if empty) */
-    newestEvent: number | null;
-}
-/**
- * Low-level NDJSON-based event storage.
- *
- * Handles file I/O, append-only writes, range reads, compaction,
- * and lock-based concurrent access prevention.
- */
-export declare class EventStore {
-    private readonly eventsPath;
-    private readonly indexPath;
-    private readonly lockPath;
-    private readonly baseDir;
-    private lockHolder;
-    constructor(storagePath: string);
-    /**
-     * Append a single event to the NDJSON file and update the index.
-     */
-    append(event: RunEvent): Promise<void>;
-    /**
-     * Read and parse all events from storage.
-     */
-    readAll(): Promise<RunEvent[]>;
-    /**
-     * Read events within a time range [startTime, endTime].
-     */
-    readRange(startTime: number, endTime: number): Promise<RunEvent[]>;
-    /**
-     * Compact the event store to keep at most `maxEvents` events.
-     * Oldest events are evicted first. Rewrites the NDJSON file atomically.
-     *
-     * @returns The number of evicted events.
-     */
-    compact(maxEvents: number): Promise<number>;
-    /**
-     * Atomically replace all events in storage with the given array.
-     * Rewrites the NDJSON file and rebuilds the index.
-     */
-    writeAll(events: RunEvent[]): Promise<void>;
-    /**
-     * Get storage statistics.
-     */
-    getStats(): Promise<StorageStats>;
-    /**
-     * Acquire a file-based lock for concurrent access prevention.
-     * Throws if the lock is already held by another process.
-     */
-    acquireLock(): Promise<void>;
-    /**
-     * Release the file-based lock.
-     */
-    releaseLock(): Promise<void>;
-    /**
-     * Remove all storage files (events, index, lock).
-     */
-    destroy(): Promise<void>;
-    /**
-     * Ensure the storage directory exists.
-     */
-    private ensureDirectory;
-    /**
-     * Parse an NDJSON string into RunEvent array, skipping blank/invalid lines.
-     */
-    private parseNdjson;
-    /**
-     * Read the index file, returning a default if it does not exist.
-     */
-    private readIndex;
-    /**
-     * Update the index with a new event.
-     */
-    private updateIndex;
-    /**
-     * Rebuild the index from a given set of events.
-     */
-    private rebuildIndex;
-}
-/**
- * A RunLedger subclass that persists events to NDJSON file storage.
- *
- * Extends the in-memory RunLedger with:
- * - Automatic persistence on logEvent()
- * - Load from storage on init via importEvents()
- * - Explicit save()/load() for bulk operations
- * - Compaction to enforce maxEvents limit
- * - Storage statistics
- * - Automatic periodic compaction via interval timer
- */
-export declare class PersistentLedger extends RunLedger {
-    private readonly config;
-    private readonly store;
-    private compactTimer;
-    private initialized;
-    constructor(config?: Partial<PersistenceConfig>);
-    /**
-     * Initialize the persistent ledger: load existing events from storage
-     * and start the compaction timer.
-     */
-    init(): Promise<void>;
-    /**
-     * Override logEvent to also persist the event to storage.
-     */
-    logEvent(event: RunEvent | Omit<RunEvent, 'eventId'>): RunEvent;
-    /**
-     * Override importEvents to also persist imported events to storage.
-     */
-    importEvents(events: RunEvent[]): void;
-    /**
-     * Flush all in-memory events to storage, replacing the storage contents.
-     * This performs a full atomic rewrite of the NDJSON file.
-     */
-    save(): Promise<void>;
-    /**
-     * Restore events from storage into memory.
-     * Clears the in-memory ledger first, then loads all stored events.
-     */
-    load(): Promise<void>;
-    /**
-     * Compact the storage to keep at most maxEvents events.
-     * Also updates the in-memory ledger to match.
-     *
-     * @returns The number of evicted events.
-     */
-    compact(): Promise<number>;
-    /**
-     * Get storage statistics.
-     */
-    getStorageStats(): Promise<StorageStats>;
-    /**
-     * Clean up resources (stop compaction timer, release locks, etc.).
-     */
-    destroy(): Promise<void>;
-    /**
-     * Get the underlying EventStore (for advanced use / testing).
-     */
-    getEventStore(): EventStore;
-    private startCompactTimer;
-    private stopCompactTimer;
-}
-/**
- * Create a PersistentLedger instance. Call `init()` after creation to load
- * existing events from storage.
- */
-export declare function createPersistentLedger(config?: Partial<PersistenceConfig>): PersistentLedger;
-/**
- * Create an EventStore instance for direct low-level storage access.
- */
-export declare function createEventStore(path: string): EventStore;
-//# sourceMappingURL=persistence.d.ts.map