mcard-js/dist/ptr/CLMIntrospection.d.ts

MCard - Content-addressable storage with cryptographic hashing, handle resolution, and vector search for Node.js and browsers

/**
 * CLM Introspection - Recursive CLM Hierarchy Analysis
 *
 * This module provides introspection capabilities for CLM (Cubical Logic Model)
 * hierarchies, enabling formal inspection of recursive CLM composition.
 *
 * ## Recursive CLM Composition
 *
 * CLMs can compose recursively, creating hierarchies of specifications:
 *
 * ```
 * Root CLM (Chapter)
 * ├── Sub-CLM A (referenced PCard)
 * │   ├── Leaf CLM X
 * │   └── Leaf CLM Y
 * └── Sub-CLM B (referenced PCard)
 *     └── Leaf CLM Z
 * ```
 *
 * This module enables:
 * - Traversal of CLM dependency graphs
 * - Detection of circular dependencies
 * - Extraction of CLM metadata at any level
 * - Composition path tracing
 *
 * ## SMC Structure Preservation
 *
 * The introspection respects the Symmetric Monoidal Category structure:
 * - Composition paths preserve associativity
 * - Parallel compositions are correctly identified
 * - Identity CLMs are recognized
 *
 * @see CLM_MCard_REPL_Implementation.md §8: Recursive CLM Composition
 * @see PTR_MCard_CLM_Recent_Developments_Jan2026.md §4.2: Recursive Structure
 */
/**
 * Type classification for CLM nodes
 */
export declare enum CLMType {
    CHAPTER = "chapter",// Has chapter metadata
    PCARD = "pcard",// Pure PCard (no chapter wrapper)
    COMPOSED = "composed",// Sequential composition (andThen)
    PARALLEL = "parallel",// Tensor product (andAlso)
    REFERENCE = "reference",// Reference to another CLM by hash
    UNKNOWN = "unknown"
}
/**
 * Type of composition between CLMs
 */
export declare enum CompositionType {
    SEQUENTIAL = "sequential",// A ; B (Coend composition)
    PARALLEL = "parallel",// A ⊗ B (Tensor product)
    NONE = "none"
}
/**
 * Represents a node in the CLM hierarchy tree
 */
export interface CLMNode {
    /** Content hash (MCard identity) */
    hash: string;
    /** Node classification */
    clmType: CLMType;
    /** CLM dimensions */
    abstract?: Record<string, any>;
    concrete?: Record<string, any>;
    balanced?: Record<string, any>;
    /** Chapter metadata (if present) */
    chapter?: Record<string, any>;
    /** Composition metadata */
    compositionType: CompositionType;
    /** Children nodes (for composed CLMs) */
    children: CLMNode[];
    /** Parent hash (for traversal) */
    parentHash?: string;
    /** Depth in the hierarchy (root = 0) */
    depth: number;
    /** Declared runtime */
    runtime: string;
}
/**
 * Result of CLM hierarchy introspection
 */
export interface CLMIntrospectionResult {
    /** Root node of the hierarchy */
    root: CLMNode;
    /** All nodes indexed by hash */
    nodes: Map<string, CLMNode>;
    /** Maximum depth of the hierarchy */
    maxDepth: number;
    /** Total node count */
    nodeCount: number;
    /** Detected circular dependencies */
    cycles: string[][];
    /** Runtime distribution */
    runtimes: Map<string, number>;
    /** Composition statistics */
    sequentialCount: number;
    parallelCount: number;
    leafCount: number;
}
/**
 * Recursive CLM Hierarchy Introspector
 *
 * Analyzes CLM composition graphs, extracting structure and metadata
 * from arbitrarily nested CLM hierarchies.
 *
 * ## Usage
 *
 * ```typescript
 * const introspector = new CLMIntrospector(collection);
 * const result = await introspector.introspect("root_pcard_hash");
 *
 * // Access hierarchy
 * console.log(result.root.chapter);
 * for (const child of result.root.children) {
 *     console.log(`  - ${child.hash}: ${child.clmType}`);
 * }
 *
 * // Check for cycles
 * if (result.cycles.length > 0) {
 *     console.log(`Circular dependencies detected: ${result.cycles}`);
 * }
 * ```
 */
export declare class CLMIntrospector {
    private collection;
    private maxDepth;
    private visited;
    private nodes;
    private cycles;
    constructor(collection?: any, maxDepth?: number);
    /**
     * Introspect a CLM hierarchy starting from the given root
     */
    introspect(pcardHash: string): Promise<CLMIntrospectionResult>;
    /**
     * Recursively build the CLM tree from a PCard hash
     */
    private buildTree;
    /**
     * Get CLM data from a PCard hash
     */
    private getCLMData;
    /**
     * Create a CLMNode from parsed CLM data
     */
    private createNode;
    /**
     * Classify the CLM by its structure
     */
    private classifyCLM;
    /**
     * Count nodes by runtime
     */
    private countRuntimes;
    /**
     * Count sequential, parallel, and leaf compositions
     */
    private countCompositions;
    /**
     * Generate a tree visualization of the CLM hierarchy
     */
    toTreeString(result: CLMIntrospectionResult): string;
    /**
     * Recursive helper for tree visualization
     */
    private treeToString;
}
//# sourceMappingURL=CLMIntrospection.d.ts.map