@llm-dev-ops/agentics-cli 1.4.59 → 1.4.68

package/dist/routing/capability-classifier.js

@@ -0,0 +1,157 @@
+/**
+ * Capability Classifier (ADR-030)
+ *
+ * Extracts capability names from a user prompt by matching against
+ * the ecosystem graph's capability names and tags.
+ *
+ * Classification strategy (ordered by priority):
+ * 1. Exact match — prompt contains a capability name verbatim
+ * 2. Tag match  — prompt contains a tag from a capability entry
+ * 3. Description match — prompt words overlap with capability descriptions
+ *
+ * No LLM calls. Pure keyword extraction for deterministic, zero-latency routing.
+ */
+// ============================================================================
+// Tokenization
+// ============================================================================
+/**
+ * Normalize and tokenize a user prompt for matching.
+ * Produces lowercase tokens with punctuation stripped.
+ */
+function tokenize(prompt) {
+    return prompt
+        .toLowerCase()
+        .replace(/[^a-z0-9\s\-_]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length >= 2);
+}
+/**
+ * Build a set of n-grams (1-gram, 2-gram, 3-gram) from tokens
+ * for multi-word matching against tags like "cold-start" or "root-cause".
+ */
+function buildNgrams(tokens) {
+    const ngrams = new Set();
+    for (const token of tokens) {
+        ngrams.add(token);
+    }
+    for (let i = 0; i < tokens.length - 1; i++) {
+        ngrams.add(`${tokens[i]}-${tokens[i + 1]}`);
+        ngrams.add(`${tokens[i]}_${tokens[i + 1]}`);
+        ngrams.add(`${tokens[i]}${tokens[i + 1]}`);
+    }
+    for (let i = 0; i < tokens.length - 2; i++) {
+        ngrams.add(`${tokens[i]}-${tokens[i + 1]}-${tokens[i + 2]}`);
+        ngrams.add(`${tokens[i]}_${tokens[i + 1]}_${tokens[i + 2]}`);
+    }
+    return ngrams;
+}
+// ============================================================================
+// Stop Words
+// ============================================================================
+/**
+ * Common English stop words that should not trigger capability matches.
+ */
+const STOP_WORDS = new Set([
+    'the', 'is', 'at', 'which', 'on', 'for', 'to', 'in', 'of', 'and',
+    'or', 'not', 'be', 'are', 'was', 'were', 'been', 'being', 'have',
+    'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should',
+    'may', 'might', 'shall', 'can', 'need', 'dare', 'ought', 'used',
+    'this', 'that', 'these', 'those', 'am', 'an', 'as', 'but', 'by',
+    'from', 'if', 'into', 'it', 'its', 'my', 'no', 'so', 'than',
+    'too', 'very', 'just', 'about', 'above', 'after', 'all', 'also',
+    'any', 'because', 'before', 'between', 'both', 'each', 'few',
+    'how', 'me', 'more', 'most', 'much', 'must', 'nor', 'only', 'other',
+    'our', 'out', 'over', 'own', 'same', 'she', 'some', 'such', 'then',
+    'there', 'they', 'through', 'under', 'up', 'what', 'when', 'where',
+    'who', 'why', 'with', 'you', 'your', 'we', 'he', 'her', 'him',
+    'his', 'us', 'them', 'their', 'here',
+]);
+// ============================================================================
+// Classifier
+// ============================================================================
+/**
+ * Classify a user prompt against the ecosystem capability graph.
+ *
+ * Returns matched capabilities with confidence scores and match metadata.
+ * Zero-cost: no LLM calls, no network, no async.
+ */
+export function classifyCapabilities(prompt, graph) {
+    const tokens = tokenize(prompt);
+    const significantTokens = tokens.filter(t => !STOP_WORDS.has(t));
+    const ngrams = buildNgrams(significantTokens);
+    const promptLower = prompt.toLowerCase();
+    const matches = new Map();
+    for (const cap of graph.capabilities) {
+        // Strategy 1: Exact capability name match
+        // Normalize capability name for matching (e.g., "erp_integration" → "erp integration")
+        const nameNormalized = cap.name.replace(/_/g, ' ').toLowerCase();
+        const nameUnderscore = cap.name.toLowerCase();
+        if (promptLower.includes(nameNormalized) || promptLower.includes(nameUnderscore)) {
+            setMatch(matches, cap, 'exact', [cap.name], 1.0);
+            continue;
+        }
+        // Also check individual name parts (e.g., "erp_integration" splits to "erp", "integration")
+        const nameParts = cap.name.toLowerCase().split('_').filter(p => p.length >= 3);
+        const namePartMatches = nameParts.filter(part => !STOP_WORDS.has(part) && ngrams.has(part));
+        if (namePartMatches.length === nameParts.length && nameParts.length > 0) {
+            setMatch(matches, cap, 'exact', namePartMatches, 0.95);
+            continue;
+        }
+        // Strategy 2: Tag match
+        const tagMatches = findTagMatches(cap, ngrams);
+        if (tagMatches.length > 0) {
+            // Confidence scales with number of matching tags, capped at 0.9
+            const tagConfidence = Math.min(0.9, 0.5 + tagMatches.length * 0.1);
+            setMatch(matches, cap, 'tag', tagMatches, tagConfidence);
+            continue;
+        }
+        // Strategy 3: Description match (lowest confidence)
+        if (cap.description) {
+            const descTokens = tokenize(cap.description).filter(t => !STOP_WORDS.has(t) && t.length >= 3);
+            const descMatches = descTokens.filter(dt => ngrams.has(dt));
+            // Require at least 2 description word matches to avoid false positives
+            if (descMatches.length >= 2) {
+                const descConfidence = Math.min(0.6, 0.2 + descMatches.length * 0.1);
+                setMatch(matches, cap, 'description', descMatches, descConfidence);
+            }
+        }
+    }
+    const capabilities = Array.from(matches.values())
+        .sort((a, b) => b.confidence - a.confidence);
+    return {
+        capabilities,
+        promptTokens: significantTokens,
+    };
+}
+function findTagMatches(cap, ngrams) {
+    if (!cap.tags || cap.tags.length === 0)
+        return [];
+    const matched = [];
+    for (const tag of cap.tags) {
+        const tagLower = tag.toLowerCase();
+        if (ngrams.has(tagLower)) {
+            matched.push(tag);
+        }
+    }
+    return matched;
+}
+function setMatch(matches, cap, matchType, matchedTokens, confidence) {
+    const existing = matches.get(cap.name);
+    // Only replace if higher confidence
+    if (!existing || confidence > existing.confidence) {
+        matches.set(cap.name, {
+            name: cap.name,
+            matchType,
+            matchedTokens,
+            confidence,
+        });
+    }
+}
+/**
+ * Extract just the capability names from a classification result.
+ * Convenience method for the router.
+ */
+export function extractCapabilityNames(result) {
+    return result.capabilities.map(c => c.name);
+}
+//# sourceMappingURL=capability-classifier.js.map

package/dist/routing/capability-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-classifier.js","sourceRoot":"","sources":["../../src/routing/capability-classifier.ts"],"names":[],"mappings":"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"}

package/dist/routing/composition-engine.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Composition Engine (ADR-031 Phase 3)
+ *
+ * Evaluates composition rules that encode expert knowledge about
+ * capability interactions. When certain capability combinations are
+ * detected, the engine automatically adds required companion capabilities.
+ *
+ * Example: erp_integration + security_validation → add data_security
+ *
+ * Rules are defined in the ecosystem graph's `compositions` array.
+ * The engine iterates until no new capabilities are added, with a
+ * maximum of 3 iterations to prevent runaway rule chains.
+ */
+export type CompositionOperator = 'all' | 'any';
+export type CompositionPriority = 'required' | 'recommended' | 'optional';
+export interface CompositionRule {
+    readonly id: string;
+    readonly when: readonly string[];
+    readonly operator: CompositionOperator;
+    readonly add: readonly string[];
+    readonly reason: string;
+    readonly priority: CompositionPriority;
+}
+export interface CompositionResult {
+    /** Final set of capabilities after composition rules are applied. */
+    readonly capabilities: readonly string[];
+    /** Capabilities that were added by composition rules. */
+    readonly added: readonly string[];
+    /** Rules that fired and their details. */
+    readonly firedRules: readonly FiredRule[];
+    /** Number of iterations performed. */
+    readonly iterations: number;
+}
+export interface FiredRule {
+    readonly ruleId: string;
+    readonly reason: string;
+    readonly addedCapabilities: readonly string[];
+    readonly priority: CompositionPriority;
+}
+/**
+ * Apply composition rules to expand the capability set.
+ *
+ * Iterates until no new capabilities are added or MAX_ITERATIONS is reached.
+ * Only 'required' rules always fire. 'recommended' rules fire if under
+ * the agent budget threshold. 'optional' rules are never auto-applied.
+ *
+ * @param capabilities - Initial set of classified capabilities
+ * @param rules - Composition rules from the graph
+ * @param validCapabilities - Set of all valid capability names in the graph
+ * @param options - Budget and control options
+ */
+export declare function applyCompositions(capabilities: readonly string[], rules: readonly CompositionRule[], validCapabilities: ReadonlySet<string>, options?: CompositionOptions): CompositionResult;
+export interface CompositionOptions {
+    /** Current agent count before composition. */
+    readonly currentAgentCount?: number;
+    /** Total agent budget ceiling. */
+    readonly agentBudget?: number;
+}
+/**
+ * Validate composition rules for structural correctness.
+ * Returns error messages or empty array.
+ */
+export declare function validateCompositionRules(rules: readonly CompositionRule[], validCapabilities: ReadonlySet<string>): string[];
+/**
+ * Detect cycles in composition rules.
+ * A cycle occurs when rule A adds capability X, and rule B (triggered by X) adds
+ * a capability that triggers rule A.
+ */
+export declare function detectCompositionCycles(rules: readonly CompositionRule[]): {
+    hasCycle: boolean;
+    cycleNodes: string[];
+};
+/**
+ * Format composition result as a human-readable explanation.
+ */
+export declare function formatCompositionExplanation(result: CompositionResult): string;
+//# sourceMappingURL=composition-engine.d.ts.map

package/dist/routing/composition-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-engine.d.ts","sourceRoot":"","sources":["../../src/routing/composition-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,CAAC;AAChD,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;CACxC;AAYD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,OAAO,CAAC,EAAE,kBAAkB,GAC3B,iBAAiB,CAiEnB;AAED,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAuBD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,MAAM,EAAE,CAgEV;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAqD7C;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAa9E"}

package/dist/routing/composition-engine.js

@@ -0,0 +1,249 @@
+/**
+ * Composition Engine (ADR-031 Phase 3)
+ *
+ * Evaluates composition rules that encode expert knowledge about
+ * capability interactions. When certain capability combinations are
+ * detected, the engine automatically adds required companion capabilities.
+ *
+ * Example: erp_integration + security_validation → add data_security
+ *
+ * Rules are defined in the ecosystem graph's `compositions` array.
+ * The engine iterates until no new capabilities are added, with a
+ * maximum of 3 iterations to prevent runaway rule chains.
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+const MAX_ITERATIONS = 3;
+// ============================================================================
+// Engine
+// ============================================================================
+/**
+ * Apply composition rules to expand the capability set.
+ *
+ * Iterates until no new capabilities are added or MAX_ITERATIONS is reached.
+ * Only 'required' rules always fire. 'recommended' rules fire if under
+ * the agent budget threshold. 'optional' rules are never auto-applied.
+ *
+ * @param capabilities - Initial set of classified capabilities
+ * @param rules - Composition rules from the graph
+ * @param validCapabilities - Set of all valid capability names in the graph
+ * @param options - Budget and control options
+ */
+export function applyCompositions(capabilities, rules, validCapabilities, options) {
+    if (rules.length === 0 || capabilities.length === 0) {
+        return {
+            capabilities,
+            added: [],
+            firedRules: [],
+            iterations: 0,
+        };
+    }
+    const currentAgentCount = options?.currentAgentCount ?? 0;
+    const agentBudget = options?.agentBudget ?? 15;
+    const result = new Set(capabilities);
+    const added = [];
+    const firedRules = [];
+    let iterations = 0;
+    let changed = true;
+    while (changed && iterations < MAX_ITERATIONS) {
+        changed = false;
+        iterations++;
+        for (const rule of rules) {
+            // Check if the rule's trigger condition is met
+            if (!evaluateCondition(rule, result))
+                continue;
+            // Determine which capabilities to add
+            for (const capToAdd of rule.add) {
+                if (result.has(capToAdd))
+                    continue;
+                if (!validCapabilities.has(capToAdd))
+                    continue;
+                if (rule.priority === 'required') {
+                    result.add(capToAdd);
+                    added.push(capToAdd);
+                    changed = true;
+                }
+                else if (rule.priority === 'recommended' &&
+                    currentAgentCount < agentBudget * 0.8) {
+                    result.add(capToAdd);
+                    added.push(capToAdd);
+                    changed = true;
+                }
+                // 'optional' rules are not auto-applied
+            }
+            // Record the fired rule if it added anything
+            const ruleAdded = rule.add.filter(c => added.includes(c));
+            if (ruleAdded.length > 0 && !firedRules.some(f => f.ruleId === rule.id)) {
+                firedRules.push({
+                    ruleId: rule.id,
+                    reason: rule.reason,
+                    addedCapabilities: ruleAdded,
+                    priority: rule.priority,
+                });
+            }
+        }
+    }
+    return {
+        capabilities: Array.from(result),
+        added,
+        firedRules,
+        iterations,
+    };
+}
+// ============================================================================
+// Rule Evaluation
+// ============================================================================
+/**
+ * Evaluate whether a composition rule's trigger condition is met.
+ */
+function evaluateCondition(rule, capabilities) {
+    if (rule.operator === 'all') {
+        return rule.when.every(c => capabilities.has(c));
+    }
+    if (rule.operator === 'any') {
+        return rule.when.some(c => capabilities.has(c));
+    }
+    return false;
+}
+// ============================================================================
+// Validation
+// ============================================================================
+/**
+ * Validate composition rules for structural correctness.
+ * Returns error messages or empty array.
+ */
+export function validateCompositionRules(rules, validCapabilities) {
+    const errors = [];
+    const ruleIds = new Set();
+    for (let i = 0; i < rules.length; i++) {
+        const rule = rules[i];
+        const prefix = `compositions[${i}]`;
+        // Unique ID
+        if (!rule.id || rule.id.length === 0) {
+            errors.push(`${prefix}.id: must be a non-empty string`);
+        }
+        else if (ruleIds.has(rule.id)) {
+            errors.push(`${prefix}.id: duplicate rule id "${rule.id}"`);
+        }
+        else {
+            ruleIds.add(rule.id);
+        }
+        // when array
+        if (!Array.isArray(rule.when) || rule.when.length === 0) {
+            errors.push(`${prefix}.when: must be a non-empty array`);
+        }
+        else {
+            for (const capName of rule.when) {
+                if (!validCapabilities.has(capName)) {
+                    errors.push(`${prefix}.when: references unknown capability "${capName}"`);
+                }
+            }
+        }
+        // operator
+        if (rule.operator !== 'all' && rule.operator !== 'any') {
+            errors.push(`${prefix}.operator: must be "all" or "any", got "${String(rule.operator)}"`);
+        }
+        // add array
+        if (!Array.isArray(rule.add) || rule.add.length === 0) {
+            errors.push(`${prefix}.add: must be a non-empty array`);
+        }
+        else {
+            for (const capName of rule.add) {
+                if (!validCapabilities.has(capName)) {
+                    errors.push(`${prefix}.add: references unknown capability "${capName}"`);
+                }
+            }
+        }
+        // reason
+        if (!rule.reason || rule.reason.length === 0) {
+            errors.push(`${prefix}.reason: must be a non-empty string`);
+        }
+        // priority
+        if (!['required', 'recommended', 'optional'].includes(rule.priority)) {
+            errors.push(`${prefix}.priority: must be "required", "recommended", or "optional"`);
+        }
+        // Self-reference check
+        if (rule.when && rule.add) {
+            const overlap = rule.add.filter(c => rule.when.includes(c));
+            if (overlap.length > 0) {
+                errors.push(`${prefix}: self-referencing — "when" and "add" share capabilities: ${overlap.join(', ')}`);
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Detect cycles in composition rules.
+ * A cycle occurs when rule A adds capability X, and rule B (triggered by X) adds
+ * a capability that triggers rule A.
+ */
+export function detectCompositionCycles(rules) {
+    // Build adjacency: for each rule, "when" caps point to "add" caps
+    const adj = new Map();
+    const allNodes = new Set();
+    for (const rule of rules) {
+        for (const trigger of rule.when) {
+            allNodes.add(trigger);
+            if (!adj.has(trigger))
+                adj.set(trigger, new Set());
+            for (const target of rule.add) {
+                allNodes.add(target);
+                adj.get(trigger).add(target);
+            }
+        }
+        for (const target of rule.add) {
+            allNodes.add(target);
+            if (!adj.has(target))
+                adj.set(target, new Set());
+        }
+    }
+    // Kahn's algorithm
+    const inDegree = new Map();
+    for (const node of allNodes) {
+        inDegree.set(node, 0);
+    }
+    for (const [, neighbors] of adj) {
+        for (const n of neighbors) {
+            inDegree.set(n, (inDegree.get(n) ?? 0) + 1);
+        }
+    }
+    const queue = [];
+    for (const [node, degree] of inDegree) {
+        if (degree === 0)
+            queue.push(node);
+    }
+    const sorted = [];
+    while (queue.length > 0) {
+        const node = queue.shift();
+        sorted.push(node);
+        for (const neighbor of adj.get(node) ?? []) {
+            const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+            inDegree.set(neighbor, newDegree);
+            if (newDegree === 0)
+                queue.push(neighbor);
+        }
+    }
+    if (sorted.length < allNodes.size) {
+        const cycleNodes = Array.from(allNodes).filter(n => !sorted.includes(n));
+        return { hasCycle: true, cycleNodes };
+    }
+    return { hasCycle: false, cycleNodes: [] };
+}
+/**
+ * Format composition result as a human-readable explanation.
+ */
+export function formatCompositionExplanation(result) {
+    if (result.firedRules.length === 0) {
+        return '';
+    }
+    const lines = [];
+    for (const rule of result.firedRules) {
+        lines.push(`  Composition rule "${rule.ruleId}" triggered:`);
+        lines.push(`    added: [${rule.addedCapabilities.join(', ')}]`);
+        lines.push(`    reason: ${rule.reason}`);
+        lines.push(`    priority: ${rule.priority}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=composition-engine.js.map

package/dist/routing/composition-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition-engine.js","sourceRoot":"","sources":["../../src/routing/composition-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoCH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAA+B,EAC/B,KAAiC,EACjC,iBAAsC,EACtC,OAA4B;IAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,OAAO;YACL,YAAY;YACZ,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,EAAE;YACd,UAAU,EAAE,CAAC;SACd,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,OAAO,EAAE,iBAAiB,IAAI,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,EAAE,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,YAAY,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,OAAO,OAAO,IAAI,UAAU,GAAG,cAAc,EAAE,CAAC;QAC9C,OAAO,GAAG,KAAK,CAAC;QAChB,UAAU,EAAE,CAAC;QAEb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,+CAA+C;YAC/C,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC;gBAAE,SAAS;YAE/C,sCAAsC;YACtC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAChC,IAAI,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAAE,SAAS;gBACnC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAAE,SAAS;gBAE/C,IAAI,IAAI,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;oBACjC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBACrB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACrB,OAAO,GAAG,IAAI,CAAC;gBACjB,CAAC;qBAAM,IACL,IAAI,CAAC,QAAQ,KAAK,aAAa;oBAC/B,iBAAiB,GAAG,WAAW,GAAG,GAAG,EACrC,CAAC;oBACD,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBACrB,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACrB,OAAO,GAAG,IAAI,CAAC;gBACjB,CAAC;gBACD,wCAAwC;YAC1C,CAAC;YAED,6CAA6C;YAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1D,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBACxE,UAAU,CAAC,IAAI,CAAC;oBACd,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,iBAAiB,EAAE,SAAS;oBAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,KAAK;QACL,UAAU;QACV,UAAU;KACX,CAAC;AACJ,CAAC;AASD,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;GAEG;AACH,SAAS,iBAAiB,CAAC,IAAqB,EAAE,YAAiC;IACjF,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAiC,EACjC,iBAAsC;IAEtC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC;QAEpC,YAAY;QACZ,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,iCAAiC,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,2BAA2B,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvB,CAAC;QAED,aAAa;QACb,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,kCAAkC,CAAC,CAAC;QAC3D,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBAChC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBACpC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,yCAAyC,OAAO,GAAG,CAAC,CAAC;gBAC5E,CAAC;YACH,CAAC;QACH,CAAC;QAED,WAAW;QACX,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,2CAA2C,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5F,CAAC;QAED,YAAY;QACZ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,iCAAiC,CAAC,CAAC;QAC1D,CAAC;aAAM,CAAC;YACN,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC/B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;oBACpC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,wCAAwC,OAAO,GAAG,CAAC,CAAC;gBAC3E,CAAC;YACH,CAAC;QACH,CAAC;QAED,SAAS;QACT,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,qCAAqC,CAAC,CAAC;QAC9D,CAAC;QAED,WAAW;QACX,IAAI,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,6DAA6D,CAAC,CAAC;QACtF,CAAC;QAED,uBAAuB;QACvB,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,6DAA6D,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC1G,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAiC;IAEjC,kEAAkE;IAClE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAChC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YACnD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;gBAC9B,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACrB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,KAAK,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACtC,IAAI,MAAM,KAAK,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,KAAK,MAAM,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACpD,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAClC,IAAI,SAAS,KAAK,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACxC,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAyB;IACpE,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,MAAM,cAAc,CAAC,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChE,KAAK,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,iBAAiB,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/routing/graph-federation.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Graph Federation (ADR-031 Phase 4)
+ *
+ * Supports splitting the monolithic ecosystem.graph.json into per-capability
+ * fragment files under docs/ecosystem.fragments/. The loader detects the
+ * graph format and uses either monolithic or federated loading.
+ *
+ * Fragment format: Each file declares a single capability with an owner field.
+ * Root graph in v2.0 format contains metadata, stages, compositions, and
+ * a fragments_dir pointer instead of inline capabilities.
+ */
+import type { StageName } from './graph-loader.js';
+import type { AgentInput } from './weighted-resolver.js';
+import type { CompositionRule } from './composition-engine.js';
+export interface CapabilityFragment {
+    readonly capability: string;
+    readonly description?: string;
+    readonly owner?: string;
+    readonly repos: readonly string[];
+    readonly agents: readonly AgentInput[];
+    readonly stage?: StageName;
+    readonly depends_on?: readonly string[];
+    readonly tags?: readonly string[];
+}
+export interface FederatedRootGraph {
+    readonly version: string;
+    readonly description?: string;
+    readonly stages?: readonly StageName[];
+    readonly fragments_dir: string;
+    readonly compositions?: readonly CompositionRule[];
+    readonly overrides?: Readonly<Record<string, FragmentOverride>>;
+}
+export interface FragmentOverride {
+    readonly max_agents?: number;
+    readonly stage?: StageName;
+}
+export interface FederationResult {
+    readonly fragments: readonly CapabilityFragment[];
+    readonly root: FederatedRootGraph;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Detect whether a parsed graph root uses federated mode (v2.0+).
+ * Federated graphs have a `fragments_dir` field instead of `capabilities`.
+ */
+export declare function isFederatedGraph(data: Record<string, unknown>): boolean;
+/**
+ * Load all capability fragments from the fragments directory.
+ * Returns the merged result with fragments, warnings, and errors.
+ */
+export declare function loadFragments(rootGraphPath: string, fragmentsDir: string): FederationResult;
+/**
+ * Split a monolithic graph into capability fragments.
+ * Used by the `graph federate` CLI command.
+ *
+ * @param graphPath - Path to the monolithic ecosystem.graph.json
+ * @param outputDir - Directory to write fragments to
+ * @returns Summary of the federation operation
+ */
+export declare function federateGraph(graphPath: string, outputDir: string): {
+    fragmentsCreated: number;
+    rootUpdated: boolean;
+    errors: string[];
+};
+/**
+ * Convert a capability fragment back to the monolithic format.
+ * Used internally by the graph loader to unify fragment and inline formats.
+ */
+export declare function fragmentToCapabilityEntry(fragment: CapabilityFragment): Record<string, unknown>;
+//# sourceMappingURL=graph-federation.d.ts.map

package/dist/routing/graph-federation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-federation.d.ts","sourceRoot":"","sources":["../../src/routing/graph-federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACnD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAEvE;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,gBAAgB,CAgFlB;AAiCD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmEtE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAU/F"}