/**
 * Graph Loader
 *
 * Handles loading and saving the blessed dependency graph file.
 * The graph is stored at architecture/dependencies.json in the workspace root.
 *
 * File format (schema aimed at AI consumers):
 * {
 *     "aiInstructions": "...how AI should use the per-project fields...",
 *     "projects": {
 *         "<project>": { level, framework, shortDescription,
 *                        responsibilitiesFile, designFile, dependsOn }
 *     }
 * }
 *
 * `framework` is the project's libType — the SET of runtime environments it is
 * validated to run in, drawn from browser | react | angular | node | express
 * (e.g. ["browser","node"]). It comes from the project's `framework:` nx tags
 * and is enforced across edges by the `library-types-match-client` rule.
 *
 * The legacy format (flat { "<project>": { level, dependsOn } } map) is still
 * readable so validation against a pre-upgrade file produces a clean
 * "re-run architecture:generate" diff instead of a parse failure.
 */
import type { EnhancedGraph } from './graph-sorter';
import type { ApiContracts, ExternalSystemDecls } from './api-usage/api-relations';
/**
 * Default path for the dependencies file (relative to workspace root)
 */
export declare const DEFAULT_GRAPH_PATH = "architecture/dependencies.json";
/**
 * Top-level instructions embedded in dependencies.json telling AI how to use
 * the per-project metadata fields.
 */
export declare const AI_INSTRUCTIONS: string;
/**
 * Named command → "command — what it does" map embedded in dependencies.json.
 */
export type CommandMap = Record<string, string>;
/**
 * Commands embedded in dependencies.json so AI (and humans) know how to
 * regenerate and DISPLAY the architecture + design graphs. These work in any
 * repo consuming @webpieces/nx-webpieces-rules.
 */
export declare const GRAPH_COMMANDS: CommandMap;
/**
 * The full contents of architecture/dependencies.json.
 */
export declare class DependenciesFile {
    readonly aiInstructions: string;
    readonly commands: CommandMap;
    readonly projects: EnhancedGraph;
    /**
     * Every API contract's per-method trigger table (kind + queue name + path).
     *
     * MUST be persisted, for the same reason `callsService` must: the runtime graph is derived
     * SOLELY from this file, and `validate-runtime-architecture` re-derives from the LOADED copy
     * while generate derives from the in-memory one. A field that is scanned but not written
     * makes those two inputs differ, and the validator reports a diff no one can fix.
     */
    readonly apiContracts: ApiContracts;
    /**
     * Declared external systems (databases, buckets, ...) keyed by identity. Persisted for the
     * same reason apiContracts is: the runtime graph is derived SOLELY from this file, so a
     * declaration that is scanned but not written would make generate and validate disagree.
     */
    readonly externalSystems: ExternalSystemDecls;
    constructor(aiInstructions: string, commands: CommandMap, projects: EnhancedGraph, 
    /**
     * Every API contract's per-method trigger table (kind + queue name + path).
     *
     * MUST be persisted, for the same reason `callsService` must: the runtime graph is derived
     * SOLELY from this file, and `validate-runtime-architecture` re-derives from the LOADED copy
     * while generate derives from the in-memory one. A field that is scanned but not written
     * makes those two inputs differ, and the validator reports a diff no one can fix.
     */
    apiContracts?: ApiContracts, 
    /**
     * Declared external systems (databases, buckets, ...) keyed by identity. Persisted for the
     * same reason apiContracts is: the runtime graph is derived SOLELY from this file, so a
     * declaration that is scanned but not written would make generate and validate disagree.
     */
    externalSystems?: ExternalSystemDecls);
}
/**
 * Load the blessed graph from disk. Understands both the current wrapper
 * format and the legacy flat map (which loads with empty aiInstructions).
 *
 * @param workspaceRoot - Absolute path to workspace root
 * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
 * @returns The blessed graph file, or null if it doesn't exist
 */
export declare function loadBlessedGraph(workspaceRoot: string, graphPath?: string): DependenciesFile | null;
/**
 * Save the graph to disk in the wrapper format with the standard aiInstructions.
 *
 * @param graph - The enriched project graph to save
 * @param workspaceRoot - Absolute path to workspace root
 * @param graphPath - Relative path to graph file (default: architecture/dependencies.json)
 */
export declare function saveGraph(graph: EnhancedGraph, workspaceRoot: string, graphPath?: string, apiContracts?: ApiContracts, externalSystems?: ExternalSystemDecls): void;
/**
 * Check if the graph file exists
 */
export declare function graphFileExists(workspaceRoot: string, graphPath?: string): boolean;