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

package/dist/routing/graph-federation.js

@@ -0,0 +1,210 @@
+/**
+ * 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 * as fs from 'node:fs';
+import * as path from 'node:path';
+// ============================================================================
+// Detection
+// ============================================================================
+/**
+ * Detect whether a parsed graph root uses federated mode (v2.0+).
+ * Federated graphs have a `fragments_dir` field instead of `capabilities`.
+ */
+export function isFederatedGraph(data) {
+    return typeof data['fragments_dir'] === 'string';
+}
+// ============================================================================
+// Fragment Loading
+// ============================================================================
+/**
+ * Load all capability fragments from the fragments directory.
+ * Returns the merged result with fragments, warnings, and errors.
+ */
+export function loadFragments(rootGraphPath, fragmentsDir) {
+    const errors = [];
+    const warnings = [];
+    // Read root graph
+    let rootData;
+    try {
+        const raw = fs.readFileSync(rootGraphPath, 'utf-8');
+        rootData = JSON.parse(raw);
+    }
+    catch (err) {
+        errors.push(`Failed to read root graph: ${err.message}`);
+        return {
+            fragments: [],
+            root: { version: '2.0', fragments_dir: fragmentsDir },
+            errors,
+            warnings,
+        };
+    }
+    const root = {
+        version: rootData['version'] ?? '2.0',
+        description: rootData['description'],
+        stages: rootData['stages'],
+        fragments_dir: fragmentsDir,
+        compositions: rootData['compositions'],
+        overrides: rootData['overrides'],
+    };
+    // Resolve fragments directory relative to root graph
+    const rootDir = path.dirname(rootGraphPath);
+    const absFragDir = path.resolve(rootDir, fragmentsDir);
+    if (!fs.existsSync(absFragDir)) {
+        errors.push(`Fragments directory not found: ${absFragDir}`);
+        return { fragments: [], root, errors, warnings };
+    }
+    // Read all .graph.json files
+    const files = fs.readdirSync(absFragDir)
+        .filter(f => f.endsWith('.graph.json'))
+        .sort();
+    const fragments = [];
+    const capNames = new Set();
+    for (const file of files) {
+        const filePath = path.join(absFragDir, file);
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const data = JSON.parse(raw);
+            const fragment = parseFragment(data, file);
+            if (!fragment) {
+                errors.push(`${file}: invalid fragment format — missing "capability" field`);
+                continue;
+            }
+            // Check for duplicate capability names
+            if (capNames.has(fragment.capability)) {
+                errors.push(`${file}: duplicate capability name "${fragment.capability}"`);
+                continue;
+            }
+            capNames.add(fragment.capability);
+            // Check owner field
+            if (!fragment.owner) {
+                warnings.push(`${file}: missing "owner" field`);
+            }
+            // Apply root overrides
+            const override = root.overrides?.[fragment.capability];
+            const finalFragment = override ? applyOverride(fragment, override) : fragment;
+            fragments.push(finalFragment);
+        }
+        catch (err) {
+            errors.push(`${file}: failed to parse — ${err.message}`);
+        }
+    }
+    return { fragments, root, errors, warnings };
+}
+// ============================================================================
+// Fragment Parsing
+// ============================================================================
+function parseFragment(data, _fileName) {
+    if (typeof data['capability'] !== 'string')
+        return null;
+    return {
+        capability: data['capability'],
+        description: data['description'],
+        owner: data['owner'],
+        repos: data['repos'] ?? [],
+        agents: data['agents'] ?? [],
+        stage: data['stage'],
+        depends_on: data['depends_on'],
+        tags: data['tags'],
+    };
+}
+function applyOverride(fragment, override) {
+    return {
+        ...fragment,
+        stage: override.stage ?? fragment.stage,
+        // max_agents is applied at selection time, not stored on fragment
+    };
+}
+// ============================================================================
+// Federation Script Support
+// ============================================================================
+/**
+ * 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 function federateGraph(graphPath, outputDir) {
+    const errors = [];
+    let raw;
+    try {
+        raw = fs.readFileSync(graphPath, 'utf-8');
+    }
+    catch (err) {
+        return { fragmentsCreated: 0, rootUpdated: false, errors: [`Cannot read graph: ${err.message}`] };
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        return { fragmentsCreated: 0, rootUpdated: false, errors: [`Invalid JSON: ${err.message}`] };
+    }
+    const capabilities = data['capabilities'];
+    if (!Array.isArray(capabilities) || capabilities.length === 0) {
+        return { fragmentsCreated: 0, rootUpdated: false, errors: ['No capabilities found in graph'] };
+    }
+    // Create output directory
+    fs.mkdirSync(outputDir, { recursive: true });
+    let fragmentsCreated = 0;
+    for (const cap of capabilities) {
+        const name = cap['name'];
+        if (!name) {
+            errors.push('Skipping capability with no name');
+            continue;
+        }
+        const fragment = {
+            capability: name,
+            description: cap['description'],
+            owner: '',
+            repos: cap['repos'],
+            agents: cap['agents'],
+            stage: cap['stage'],
+            depends_on: cap['depends_on'],
+            tags: cap['tags'],
+        };
+        const fileName = `${name}.graph.json`;
+        const filePath = path.join(outputDir, fileName);
+        fs.writeFileSync(filePath, JSON.stringify(fragment, null, 2) + '\n', 'utf-8');
+        fragmentsCreated++;
+    }
+    // Update root graph to v2.0 format
+    const relativeDir = path.relative(path.dirname(graphPath), outputDir);
+    const newRoot = {
+        version: '2.0',
+        description: data['description'] ?? '',
+        stages: data['stages'],
+        fragments_dir: relativeDir,
+        compositions: data['compositions'] ?? [],
+    };
+    // Write updated root (backup original first)
+    const backupPath = graphPath + '.bak';
+    fs.copyFileSync(graphPath, backupPath);
+    fs.writeFileSync(graphPath, JSON.stringify(newRoot, null, 2) + '\n', 'utf-8');
+    return { fragmentsCreated, rootUpdated: true, errors };
+}
+/**
+ * Convert a capability fragment back to the monolithic format.
+ * Used internally by the graph loader to unify fragment and inline formats.
+ */
+export function fragmentToCapabilityEntry(fragment) {
+    return {
+        name: fragment.capability,
+        description: fragment.description,
+        repos: fragment.repos,
+        agents: fragment.agents,
+        stage: fragment.stage,
+        depends_on: fragment.depends_on ?? [],
+        tags: fragment.tags ?? [],
+    };
+}
+//# sourceMappingURL=graph-federation.js.map

package/dist/routing/graph-federation.js.map

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

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

@@ -0,0 +1,74 @@
+/**
+ * Ecosystem Capability Graph Loader (ADR-030)
+ *
+ * Reads, validates, and caches the ecosystem capability graph from
+ * docs/ecosystem.graph.json. Provides typed lookup methods for
+ * the capability classifier and graph router.
+ */
+import type { AgentInput } from './weighted-resolver.js';
+import type { CompositionRule } from './composition-engine.js';
+export type StageName = 'simulation' | 'research' | 'specification' | 'architecture' | 'build' | 'validation' | 'deployment' | 'governance';
+export interface CapabilityEntry {
+    readonly name: string;
+    readonly description?: string;
+    readonly repos: readonly string[];
+    /** Agents can be plain strings or weighted objects (ADR-031 Phase 1). */
+    readonly agents: readonly AgentInput[];
+    readonly stage?: StageName;
+    readonly depends_on?: readonly string[];
+    readonly tags?: readonly string[];
+}
+export interface EcosystemGraph {
+    readonly version: string;
+    readonly description: string;
+    readonly stages: readonly StageName[];
+    readonly capabilities: readonly CapabilityEntry[];
+    /** Composition rules for capability interaction (ADR-031 Phase 3). */
+    readonly compositions?: readonly CompositionRule[];
+    /** Fragments directory for federated mode (ADR-031 Phase 4). */
+    readonly fragments_dir?: string;
+}
+export interface GraphValidationError {
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Resolve the path to the ecosystem graph file.
+ * Looks relative to the project root (the directory containing package.json).
+ */
+export declare function resolveGraphPath(projectRoot?: string): string;
+/**
+ * Load and validate the ecosystem capability graph.
+ *
+ * Returns a validated, immutable graph object. The result is cached for the
+ * lifetime of the process. Pass `forceReload: true` to bypass the cache.
+ *
+ * @throws Error if the graph file cannot be read or fails validation.
+ */
+export declare function loadEcosystemGraph(options?: {
+    graphPath?: string;
+    forceReload?: boolean;
+}): EcosystemGraph;
+/**
+ * Clear the cached graph. Useful for testing.
+ */
+export declare function clearGraphCache(): void;
+/**
+ * Look up a capability by exact name.
+ */
+export declare function getCapabilityByName(graph: EcosystemGraph, name: string): CapabilityEntry | undefined;
+/**
+ * Find all capabilities that have a matching tag.
+ */
+export declare function getCapabilitiesByTag(graph: EcosystemGraph, tag: string): readonly CapabilityEntry[];
+/**
+ * Find all capabilities assigned to a given stage.
+ */
+export declare function getCapabilitiesByStage(graph: EcosystemGraph, stage: StageName): readonly CapabilityEntry[];
+/**
+ * Resolve the full dependency tree for a set of capability names.
+ * Returns all capability names including transitive dependencies.
+ * Uses iterative BFS to avoid stack overflow on deep graphs.
+ */
+export declare function resolveDependencies(graph: EcosystemGraph, capabilityNames: readonly string[]): readonly string[];
+//# sourceMappingURL=graph-loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-loader.d.ts","sourceRoot":"","sources":["../../src/routing/graph-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM/D,MAAM,MAAM,SAAS,GACjB,YAAY,GACZ,UAAU,GACV,eAAe,GACf,cAAc,GACd,OAAO,GACP,YAAY,GACZ,YAAY,GACZ,YAAY,CAAC;AAEjB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,yEAAyE;IACzE,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,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;IAClD,sEAAsE;IACtE,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACnD,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAiBD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAgPD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7D;AAeD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG,cAAc,CAkEjB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAEpG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAKnG;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,eAAe,EAAE,CAE1G;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,SAAS,MAAM,EAAE,CAkBnB"}

package/dist/routing/graph-loader.js

@@ -0,0 +1,383 @@
+/**
+ * Ecosystem Capability Graph Loader (ADR-030)
+ *
+ * Reads, validates, and caches the ecosystem capability graph from
+ * docs/ecosystem.graph.json. Provides typed lookup methods for
+ * the capability classifier and graph router.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// ============================================================================
+// Validation
+// ============================================================================
+const VALID_STAGES = new Set([
+    'simulation',
+    'research',
+    'specification',
+    'architecture',
+    'build',
+    'validation',
+    'deployment',
+    'governance',
+]);
+function validateGraph(data) {
+    const errors = [];
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        errors.push({ path: '$', message: 'Root must be a non-null object' });
+        return errors;
+    }
+    const obj = data;
+    // version
+    if (typeof obj['version'] !== 'string' || obj['version'].length === 0) {
+        errors.push({ path: '$.version', message: 'version must be a non-empty string' });
+    }
+    // stages (optional in v1.0, required in v1.1+)
+    if ('stages' in obj) {
+        if (!Array.isArray(obj['stages'])) {
+            errors.push({ path: '$.stages', message: 'stages must be an array' });
+        }
+        else {
+            for (let i = 0; i < obj['stages'].length; i++) {
+                const s = obj['stages'][i];
+                if (typeof s !== 'string' || !VALID_STAGES.has(s)) {
+                    errors.push({ path: `$.stages[${i}]`, message: `Invalid stage: ${String(s)}` });
+                }
+            }
+        }
+    }
+    // capabilities
+    if (!Array.isArray(obj['capabilities'])) {
+        errors.push({ path: '$.capabilities', message: 'capabilities must be an array' });
+        return errors;
+    }
+    const capNames = new Set();
+    const capabilities = obj['capabilities'];
+    for (let i = 0; i < capabilities.length; i++) {
+        const cap = capabilities[i];
+        const prefix = `$.capabilities[${i}]`;
+        if (typeof cap !== 'object' || cap === null || Array.isArray(cap)) {
+            errors.push({ path: prefix, message: 'Capability entry must be an object' });
+            continue;
+        }
+        const c = cap;
+        // name (required)
+        if (typeof c['name'] !== 'string' || c['name'].length === 0) {
+            errors.push({ path: `${prefix}.name`, message: 'name must be a non-empty string' });
+        }
+        else if (capNames.has(c['name'])) {
+            errors.push({ path: `${prefix}.name`, message: `Duplicate capability name: ${c['name']}` });
+        }
+        else {
+            capNames.add(c['name']);
+        }
+        // repos (required, non-empty array of strings)
+        if (!Array.isArray(c['repos']) || c['repos'].length === 0) {
+            errors.push({ path: `${prefix}.repos`, message: 'repos must be a non-empty array of strings' });
+        }
+        else {
+            for (let j = 0; j < c['repos'].length; j++) {
+                if (typeof c['repos'][j] !== 'string') {
+                    errors.push({ path: `${prefix}.repos[${j}]`, message: 'repo entry must be a string' });
+                }
+            }
+        }
+        // agents (required, non-empty array of strings or weighted objects)
+        if (!Array.isArray(c['agents']) || c['agents'].length === 0) {
+            errors.push({ path: `${prefix}.agents`, message: 'agents must be a non-empty array' });
+        }
+        else {
+            for (let j = 0; j < c['agents'].length; j++) {
+                const agent = c['agents'][j];
+                if (typeof agent === 'string') {
+                    // Plain string form — valid
+                    if (agent.length === 0) {
+                        errors.push({ path: `${prefix}.agents[${j}]`, message: 'agent name must be non-empty' });
+                    }
+                }
+                else if (typeof agent === 'object' && agent !== null && !Array.isArray(agent)) {
+                    // Weighted object form — validate fields
+                    const agentObj = agent;
+                    if (typeof agentObj['name'] !== 'string' || agentObj['name'].length === 0) {
+                        errors.push({ path: `${prefix}.agents[${j}].name`, message: 'agent name must be a non-empty string' });
+                    }
+                    if (typeof agentObj['weight'] === 'number') {
+                        if (agentObj['weight'] < 0 || agentObj['weight'] > 1) {
+                            errors.push({ path: `${prefix}.agents[${j}].weight`, message: `weight must be between 0.0 and 1.0, got ${agentObj['weight']}` });
+                        }
+                    }
+                    else if ('weight' in agentObj) {
+                        errors.push({ path: `${prefix}.agents[${j}].weight`, message: 'weight must be a number' });
+                    }
+                    if ('role' in agentObj && agentObj['role'] !== undefined) {
+                        const validRoles = ['primary', 'secondary', 'specialist'];
+                        if (typeof agentObj['role'] !== 'string' || !validRoles.includes(agentObj['role'])) {
+                            errors.push({ path: `${prefix}.agents[${j}].role`, message: `role must be "primary", "secondary", or "specialist"` });
+                        }
+                    }
+                }
+                else {
+                    errors.push({ path: `${prefix}.agents[${j}]`, message: 'agent must be a string or { name, weight, role } object' });
+                }
+            }
+        }
+        // stage (optional, must be valid if present)
+        if ('stage' in c && c['stage'] !== undefined) {
+            if (typeof c['stage'] !== 'string' || !VALID_STAGES.has(c['stage'])) {
+                errors.push({ path: `${prefix}.stage`, message: `Invalid stage: ${String(c['stage'])}` });
+            }
+        }
+        // depends_on (optional, array of strings)
+        if ('depends_on' in c && c['depends_on'] !== undefined) {
+            if (!Array.isArray(c['depends_on'])) {
+                errors.push({ path: `${prefix}.depends_on`, message: 'depends_on must be an array of strings' });
+            }
+            else {
+                for (let j = 0; j < c['depends_on'].length; j++) {
+                    if (typeof c['depends_on'][j] !== 'string') {
+                        errors.push({ path: `${prefix}.depends_on[${j}]`, message: 'depends_on entry must be a string' });
+                    }
+                }
+            }
+        }
+        // tags (optional, array of strings)
+        if ('tags' in c && c['tags'] !== undefined) {
+            if (!Array.isArray(c['tags'])) {
+                errors.push({ path: `${prefix}.tags`, message: 'tags must be an array of strings' });
+            }
+            else {
+                for (let j = 0; j < c['tags'].length; j++) {
+                    if (typeof c['tags'][j] !== 'string') {
+                        errors.push({ path: `${prefix}.tags[${j}]`, message: 'tag entry must be a string' });
+                    }
+                }
+            }
+        }
+    }
+    // Cross-reference: depends_on must reference existing capability names
+    for (let i = 0; i < capabilities.length; i++) {
+        const c = capabilities[i];
+        if (Array.isArray(c['depends_on'])) {
+            for (let j = 0; j < c['depends_on'].length; j++) {
+                const dep = c['depends_on'][j];
+                if (typeof dep === 'string' && !capNames.has(dep)) {
+                    errors.push({
+                        path: `$.capabilities[${i}].depends_on[${j}]`,
+                        message: `depends_on references unknown capability: ${dep}`,
+                    });
+                }
+            }
+        }
+    }
+    // Cycle detection in depends_on (Kahn's algorithm)
+    if (errors.length === 0) {
+        const cycleErrors = detectDependencyCycles(capabilities);
+        errors.push(...cycleErrors);
+    }
+    return errors;
+}
+function detectDependencyCycles(capabilities) {
+    const adj = new Map();
+    const inDegree = new Map();
+    for (const cap of capabilities) {
+        const name = cap['name'];
+        adj.set(name, []);
+        inDegree.set(name, 0);
+    }
+    for (const cap of capabilities) {
+        const name = cap['name'];
+        const deps = cap['depends_on'] ?? [];
+        for (const dep of deps) {
+            const neighbors = adj.get(dep);
+            if (neighbors) {
+                neighbors.push(name);
+                inDegree.set(name, (inDegree.get(name) ?? 0) + 1);
+            }
+        }
+    }
+    const queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(name);
+        }
+    }
+    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 < capabilities.length) {
+        const cycleNodes = capabilities
+            .map(c => c['name'])
+            .filter(n => !sorted.includes(n));
+        return [{
+                path: '$.capabilities',
+                message: `Circular dependency detected among capabilities: ${cycleNodes.join(', ')}`,
+            }];
+    }
+    return [];
+}
+// ============================================================================
+// Graph Loader
+// ============================================================================
+const DEFAULT_STAGES = [
+    'simulation',
+    'research',
+    'specification',
+    'architecture',
+    'build',
+    'validation',
+    'deployment',
+    'governance',
+];
+/** Cached graph instance — loaded once per process. */
+let cachedGraph = null;
+let cachedGraphPath = null;
+/**
+ * Resolve the path to the ecosystem graph file.
+ * Looks relative to the project root (the directory containing package.json).
+ */
+export function resolveGraphPath(projectRoot) {
+    const root = projectRoot ?? findProjectRoot();
+    return path.join(root, 'docs', 'ecosystem.graph.json');
+}
+function findProjectRoot() {
+    let dir = process.cwd();
+    for (let i = 0; i < 10; i++) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+}
+/**
+ * Load and validate the ecosystem capability graph.
+ *
+ * Returns a validated, immutable graph object. The result is cached for the
+ * lifetime of the process. Pass `forceReload: true` to bypass the cache.
+ *
+ * @throws Error if the graph file cannot be read or fails validation.
+ */
+export function loadEcosystemGraph(options) {
+    const graphPath = options?.graphPath ?? resolveGraphPath();
+    // Return cached if same path and not forcing reload
+    if (cachedGraph && cachedGraphPath === graphPath && !options?.forceReload) {
+        return cachedGraph;
+    }
+    // Read file
+    let raw;
+    try {
+        raw = fs.readFileSync(graphPath, 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            throw new Error(`Ecosystem graph not found at ${graphPath}. Expected docs/ecosystem.graph.json in the project root.`);
+        }
+        throw new Error(`Failed to read ecosystem graph at ${graphPath}: ${err.message}`);
+    }
+    // Parse JSON
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Ecosystem graph at ${graphPath} contains invalid JSON: ${err.message}`);
+    }
+    // Validate
+    const errors = validateGraph(data);
+    if (errors.length > 0) {
+        const details = errors.map(e => `  ${e.path}: ${e.message}`).join('\n');
+        throw new Error(`Ecosystem graph validation failed:\n${details}`);
+    }
+    // Build typed graph
+    const obj = data;
+    const rawCapabilities = obj['capabilities'];
+    const stages = (Array.isArray(obj['stages']) ? obj['stages'] : DEFAULT_STAGES);
+    const graph = {
+        version: obj['version'],
+        description: obj['description'] ?? '',
+        stages,
+        capabilities: rawCapabilities.map(c => ({
+            name: c['name'],
+            description: c['description'],
+            repos: c['repos'],
+            agents: c['agents'],
+            stage: c['stage'],
+            depends_on: c['depends_on'] ?? [],
+            tags: c['tags'] ?? [],
+        })),
+        compositions: Array.isArray(obj['compositions'])
+            ? obj['compositions']
+            : undefined,
+        fragments_dir: typeof obj['fragments_dir'] === 'string'
+            ? obj['fragments_dir']
+            : undefined,
+    };
+    // Cache
+    cachedGraph = graph;
+    cachedGraphPath = graphPath;
+    return graph;
+}
+/**
+ * Clear the cached graph. Useful for testing.
+ */
+export function clearGraphCache() {
+    cachedGraph = null;
+    cachedGraphPath = null;
+}
+// ============================================================================
+// Lookup Helpers
+// ============================================================================
+/**
+ * Look up a capability by exact name.
+ */
+export function getCapabilityByName(graph, name) {
+    return graph.capabilities.find(c => c.name === name);
+}
+/**
+ * Find all capabilities that have a matching tag.
+ */
+export function getCapabilitiesByTag(graph, tag) {
+    const lower = tag.toLowerCase();
+    return graph.capabilities.filter(c => c.tags?.some(t => t.toLowerCase() === lower));
+}
+/**
+ * Find all capabilities assigned to a given stage.
+ */
+export function getCapabilitiesByStage(graph, stage) {
+    return graph.capabilities.filter(c => c.stage === stage);
+}
+/**
+ * Resolve the full dependency tree for a set of capability names.
+ * Returns all capability names including transitive dependencies.
+ * Uses iterative BFS to avoid stack overflow on deep graphs.
+ */
+export function resolveDependencies(graph, capabilityNames) {
+    const resolved = new Set(capabilityNames);
+    const queue = [...capabilityNames];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const cap = getCapabilityByName(graph, current);
+        if (!cap?.depends_on)
+            continue;
+        for (const dep of cap.depends_on) {
+            if (!resolved.has(dep)) {
+                resolved.add(dep);
+                queue.push(dep);
+            }
+        }
+    }
+    return Array.from(resolved);
+}
+//# sourceMappingURL=graph-loader.js.map