@creact-labs/creact 0.1.0

package/dist/core/Reconciler.js

@@ -0,0 +1,1037 @@
+"use strict";
+/**
+
+ * Licensed under the Apache License, Version 2.0 (the "License");
+
+ * you may not use this file except in compliance with the License.
+
+ * You may obtain a copy of the License at
+
+ *
+
+ *     http://www.apache.org/licenses/LICENSE-2.0
+
+ *
+
+ * Unless required by applicable law or agreed to in writing, software
+
+ * distributed under the License is distributed on an "AS IS" BASIS,
+
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+ * See the License for the specific language governing permissions and
+
+ * limitations under the License.
+
+ *
+
+ * Copyright 2025 Daniel Coutinho Ribeiro
+
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reconciler = void 0;
+exports.getTotalChanges = getTotalChanges;
+exports.hasChanges = hasChanges;
+const deepEqual_1 = require("../utils/deepEqual");
+const errors_1 = require("./errors");
+const Logger_1 = require("../utils/Logger");
+const logger = Logger_1.LoggerFactory.getLogger('reconciler');
+/**
+ * Helper function to get total number of changes from a ChangeSet
+ * Single source of truth for change counting
+ */
+function getTotalChanges(changeSet) {
+    return (changeSet.creates.length +
+        changeSet.updates.length +
+        changeSet.deletes.length +
+        changeSet.replacements.length +
+        changeSet.moves.length);
+}
+/**
+ * Helper function to check if a ChangeSet has any changes
+ */
+function hasChanges(changeSet) {
+    return getTotalChanges(changeSet) > 0;
+}
+/**
+ * Reconciler computes minimal change sets between CloudDOM states
+ *
+ * This is CReact's equivalent to React's Fiber reconciliation algorithm.
+ * It enables:
+ * - Incremental updates (only deploy what changed)
+ * - Plan preview (show diff before deploy)
+ * - Hot reload (apply deltas without full rebuild)
+ * - Dependency-aware ordering (deploy in correct order)
+ *
+ * REQ-O01: CloudDOM State Machine
+ * REQ-O04: Plan and Change Preview
+ */
+class Reconciler {
+    constructor() {
+        /**
+         * Internal methods exposed for testing
+         *
+         * These are pure functions that are ideal for unit testing.
+         * Prefixed with __ to indicate they're internal/testing-only.
+         */
+        this.__testing__ = {
+            buildDependencyGraph: this.buildDependencyGraph.bind(this),
+            detectChangeType: this.detectChangeType.bind(this),
+            computeParallelBatches: this.computeParallelBatches.bind(this),
+            topologicalSort: this.topologicalSort.bind(this),
+            extractDependencies: this.extractDependencies.bind(this),
+            detectMoves: this.detectMoves.bind(this),
+            validateGraph: this.validateGraph.bind(this),
+            computeShallowHash: this.computeShallowHash.bind(this),
+            isMetadataKey: this.isMetadataKey.bind(this),
+        };
+    }
+    /**
+     * Generate a human-readable diff visualization for UI/CLI
+     *
+     * Formats the ChangeSet as JSON suitable for:
+     * - CLI diff previews (like Terraform plans)
+     * - Web UI diff visualization
+     * - CI/CD pipeline reports
+     *
+     * @param changeSet - ChangeSet to visualize
+     * @returns JSON-serializable diff visualization
+     */
+    generateDiffVisualization(changeSet) {
+        const changes = [];
+        // Add creates
+        for (const node of changeSet.creates) {
+            changes.push({
+                type: 'create',
+                nodeId: node.id,
+                details: {
+                    construct: this.getConstructName(node.construct),
+                    path: node.path,
+                },
+            });
+        }
+        // Add updates
+        for (const node of changeSet.updates) {
+            changes.push({
+                type: 'update',
+                nodeId: node.id,
+                details: {
+                    construct: this.getConstructName(node.construct),
+                    path: node.path,
+                },
+            });
+        }
+        // Add deletes
+        for (const node of changeSet.deletes) {
+            changes.push({
+                type: 'delete',
+                nodeId: node.id,
+                details: {
+                    construct: this.getConstructName(node.construct),
+                    path: node.path,
+                },
+            });
+        }
+        // Add replacements
+        for (const node of changeSet.replacements) {
+            changes.push({
+                type: 'replacement',
+                nodeId: node.id,
+                details: {
+                    construct: this.getConstructName(node.construct),
+                    path: node.path,
+                },
+            });
+        }
+        // Add moves
+        for (const move of changeSet.moves) {
+            changes.push({
+                type: 'move',
+                nodeId: move.nodeId,
+                details: {
+                    from: move.from,
+                    to: move.to,
+                },
+            });
+        }
+        // Format batches
+        const batches = changeSet.parallelBatches.map((batch, index) => ({
+            depth: index,
+            nodes: batch,
+            parallelism: batch.length,
+        }));
+        return {
+            summary: {
+                creates: changeSet.creates.length,
+                updates: changeSet.updates.length,
+                deletes: changeSet.deletes.length,
+                replacements: changeSet.replacements.length,
+                moves: changeSet.moves.length,
+                total: changes.length,
+            },
+            changes,
+            deployment: {
+                order: changeSet.deploymentOrder,
+                batches,
+            },
+        };
+    }
+    /**
+     * Debug logging helper
+     * Logs messages when CREACT_DEBUG environment variable is set
+     *
+     * Supports both string messages and structured data for telemetry.
+     * Includes timestamps for async reconciliation tracing.
+     */
+    log(message) {
+        if (typeof message === 'string') {
+            logger.debug(message);
+        }
+        else {
+            logger.debug(JSON.stringify(message, null, 2));
+        }
+    }
+    /**
+     * Check if a key is internal metadata (starts with underscore)
+     *
+     * Used for filtering metadata from prop comparisons and dependency scanning.
+     *
+     * @param key - Property key to check
+     * @returns True if key is metadata
+     */
+    isMetadataKey(key) {
+        return key.startsWith('_');
+    }
+    /**
+     * Compute a shallow hash of props for fast equality checks
+     *
+     * Creates a stable, key-order-independent hash by:
+     * - Filtering out special props (metadata, key, children)
+     * - Sorting entries by key
+     * - JSON stringifying the result
+     *
+     * This enables O(1) prop comparisons for unchanged nodes.
+     *
+     * @param props - Props object to hash
+     * @returns Stable hash string
+     */
+    computeShallowHash(props) {
+        if (!props || typeof props !== 'object') {
+            return 'null';
+        }
+        const entries = Object.entries(props)
+            .filter(([k]) => !this.isMetadataKey(k) && k !== 'key' && k !== 'children')
+            .sort(([a], [b]) => a.localeCompare(b));
+        try {
+            return JSON.stringify(entries);
+        }
+        catch {
+            // If serialization fails (circular refs, functions), use fallback
+            return `hash:${Math.random()}`;
+        }
+    }
+    /**
+     * Reconcile two CloudDOM states and compute minimal change set
+     *
+     * Algorithm:
+     * 1. Build ID maps for O(n) lookup
+     * 2. Detect creates (in current, not in previous)
+     * 3. Detect updates/replacements (in both, but props or construct changed)
+     * 4. Detect deletes (in previous, not in current)
+     * 5. Detect moves (nodes that changed parent)
+     * 6. Build dependency graph from current nodes
+     * 7. Compute topological sort for deployment order
+     * 8. Group independent resources into parallel batches
+     *
+     * Performance notes:
+     * - Synchronous for graphs <10k nodes
+     * - For larger graphs, consider async version with periodic yielding
+     * - Uses memoized deep equality for prop comparison
+     *
+     * REQ-O01: Diff algorithm for incremental updates
+     * REQ-O04: Change preview for plan command
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state
+     * @returns ChangeSet with creates, updates, deletes, replacements, and deployment order
+     */
+    reconcile(previous, current) {
+        this.log('Starting reconciliation');
+        // Step 1: Build ID maps for O(n) lookup
+        const previousMap = this.buildNodeMap(previous);
+        const currentMap = this.buildNodeMap(current);
+        this.log(`Previous: ${previousMap.size} nodes, Current: ${currentMap.size} nodes`);
+        // Step 2: Detect creates (nodes in current but not in previous)
+        const creates = [];
+        for (const [id, node] of currentMap) {
+            if (!previousMap.has(id)) {
+                creates.push(node);
+            }
+        }
+        this.log(`Creates: ${creates.length} nodes`);
+        // Step 3: Detect updates and replacements (nodes in both with changes)
+        const updates = [];
+        const replacements = [];
+        for (const [id, currentNode] of currentMap) {
+            const previousNode = previousMap.get(id);
+            if (previousNode) {
+                const changeType = this.detectChangeType(previousNode, currentNode);
+                if (changeType === 'replacement') {
+                    // Construct type changed - needs replacement (delete + create)
+                    replacements.push(currentNode);
+                    this.log(`Replacement detected: ${id} (construct changed)`);
+                }
+                else if (changeType === 'update') {
+                    // Props changed but construct is same - can update in place
+                    updates.push(currentNode);
+                    this.log(`Update detected: ${id} (props changed)`);
+                }
+                // changeType === 'none' means no changes
+            }
+        }
+        this.log(`Updates: ${updates.length} nodes, Replacements: ${replacements.length} nodes`);
+        // Step 4: Detect deletes (nodes in previous but not in current)
+        const deletes = [];
+        for (const [id, node] of previousMap) {
+            if (!currentMap.has(id)) {
+                deletes.push(node);
+            }
+        }
+        this.log(`Deletes: ${deletes.length} nodes`);
+        // Step 4.5: Detect moves (nodes that changed parent in hierarchy)
+        const moves = this.detectMoves(previousMap, currentMap);
+        this.log(`Moves: ${moves.length} nodes`);
+        // Debug logging: breakdown of change types (CREACT_DEBUG only)
+        this.log('\n🔍 Reconciliation Change Breakdown:');
+        this.log(`  Creates: ${creates.length} nodes - ${creates.map((n) => n.id).join(', ') || 'none'}`);
+        this.log(`  Updates: ${updates.length} nodes - ${updates.map((n) => n.id).join(', ') || 'none'}`);
+        this.log(`  Deletes: ${deletes.length} nodes - ${deletes.map((n) => n.id).join(', ') || 'none'}`);
+        this.log(`  Replacements: ${replacements.length} nodes - ${replacements.map((n) => n.id).join(', ') || 'none'}`);
+        this.log(`  Moves: ${moves.length} nodes`);
+        if (moves.length > 0) {
+            this.log('  Move details:');
+            moves.forEach((move) => {
+                this.log(`    ${move.nodeId}: "${move.from}" → "${move.to}"`);
+            });
+        }
+        // Calculate unchanged nodes for idempotency verification
+        const unchanged = currentMap.size - (creates.length + updates.length + replacements.length);
+        this.log(`Unchanged: ${unchanged} nodes (idempotent)`);
+        // Step 5: Build dependency graph from current nodes
+        this.log('Building dependency graph');
+        const graph = this.buildDependencyGraph(Array.from(currentMap.values()));
+        // Step 6: Compute topological sort for deployment order
+        this.log('Computing deployment order');
+        const deploymentOrder = this.topologicalSort(graph);
+        // Step 7: Compute parallel deployment batches
+        this.log('Computing parallel batches');
+        const parallelBatches = this.computeParallelBatches(deploymentOrder, graph);
+        this.log(`Deployment order: ${deploymentOrder.length} nodes in ${parallelBatches.length} batches`);
+        // Structured logging for telemetry/debugging
+        this.log({
+            phase: 'reconciliation_complete',
+            summary: {
+                creates: creates.length,
+                updates: updates.length,
+                deletes: deletes.length,
+                replacements: replacements.length,
+                unchanged,
+                total: currentMap.size,
+            },
+            deployment: {
+                order: deploymentOrder,
+                batches: parallelBatches.length,
+                maxParallelism: Math.max(...parallelBatches.map((b) => b.length), 0),
+            },
+        });
+        return {
+            creates,
+            updates,
+            deletes,
+            replacements,
+            moves,
+            deploymentOrder,
+            parallelBatches,
+        };
+    }
+    /**
+     * Async reconcile for large CloudDOM graphs (>10k nodes)
+     *
+     * Yields periodically to prevent blocking the event loop.
+     * Useful for:
+     * - Large infrastructure graphs
+     * - UI responsiveness during diff computation
+     * - Long-running CI/CD pipelines
+     *
+     * Algorithm is identical to synchronous reconcile, but yields every N nodes.
+     *
+     * @param previous - Previous CloudDOM state
+     * @param current - Current CloudDOM state
+     * @param yieldInterval - Number of nodes to process before yielding (default: 1000)
+     * @returns Promise resolving to ChangeSet
+     */
+    async reconcileAsync(previous, current, yieldInterval = 1000) {
+        this.log('Starting async reconciliation');
+        // Step 1: Build ID maps for O(n) lookup
+        const previousMap = this.buildNodeMap(previous);
+        const currentMap = this.buildNodeMap(current);
+        this.log(`Previous: ${previousMap.size} nodes, Current: ${currentMap.size} nodes`);
+        // Step 2: Detect creates (with periodic yielding)
+        const creates = [];
+        let processedCount = 0;
+        for (const [id, node] of currentMap) {
+            if (!previousMap.has(id)) {
+                creates.push(node);
+            }
+            // Yield periodically to prevent blocking
+            if (++processedCount % yieldInterval === 0) {
+                await this.yield();
+            }
+        }
+        this.log(`Creates: ${creates.length} nodes`);
+        // Step 3: Detect updates and replacements (with periodic yielding)
+        const updates = [];
+        const replacements = [];
+        processedCount = 0;
+        for (const [id, currentNode] of currentMap) {
+            const previousNode = previousMap.get(id);
+            if (previousNode) {
+                const changeType = this.detectChangeType(previousNode, currentNode);
+                if (changeType === 'replacement') {
+                    replacements.push(currentNode);
+                    this.log(`Replacement detected: ${id} (construct changed)`);
+                }
+                else if (changeType === 'update') {
+                    updates.push(currentNode);
+                    this.log(`Update detected: ${id} (props changed)`);
+                }
+            }
+            // Yield periodically
+            if (++processedCount % yieldInterval === 0) {
+                await this.yield();
+            }
+        }
+        this.log(`Updates: ${updates.length} nodes, Replacements: ${replacements.length} nodes`);
+        // Step 4: Detect deletes
+        const deletes = [];
+        for (const [id, node] of previousMap) {
+            if (!currentMap.has(id)) {
+                deletes.push(node);
+            }
+        }
+        this.log(`Deletes: ${deletes.length} nodes`);
+        // Step 4.5: Detect moves
+        const moves = this.detectMoves(previousMap, currentMap);
+        this.log(`Moves: ${moves.length} nodes`);
+        // Calculate unchanged nodes
+        const unchanged = currentMap.size - (creates.length + updates.length + replacements.length);
+        this.log(`Unchanged: ${unchanged} nodes (idempotent)`);
+        // Step 5: Build dependency graph
+        this.log('Building dependency graph');
+        const graph = this.buildDependencyGraph(Array.from(currentMap.values()));
+        // Step 6: Compute topological sort
+        this.log('Computing deployment order');
+        const deploymentOrder = this.topologicalSort(graph);
+        // Step 7: Compute parallel batches
+        this.log('Computing parallel batches');
+        const parallelBatches = this.computeParallelBatches(deploymentOrder, graph);
+        this.log(`Deployment order: ${deploymentOrder.length} nodes in ${parallelBatches.length} batches`);
+        // Structured logging
+        this.log({
+            phase: 'async_reconciliation_complete',
+            summary: {
+                creates: creates.length,
+                updates: updates.length,
+                deletes: deletes.length,
+                replacements: replacements.length,
+                unchanged,
+                total: currentMap.size,
+            },
+            deployment: {
+                order: deploymentOrder,
+                batches: parallelBatches.length,
+                maxParallelism: Math.max(...parallelBatches.map((b) => b.length), 0),
+            },
+        });
+        return {
+            creates,
+            updates,
+            deletes,
+            replacements,
+            moves,
+            deploymentOrder,
+            parallelBatches,
+        };
+    }
+    /**
+     * Yield control to event loop
+     *
+     * Uses setImmediate in Node.js, setTimeout in browser.
+     * Prevents blocking during large graph reconciliation.
+     */
+    yield() {
+        return new Promise((resolve) => {
+            if (typeof setImmediate !== 'undefined') {
+                setImmediate(resolve);
+            }
+            else {
+                setTimeout(resolve, 0);
+            }
+        });
+    }
+    /**
+     * Build a flat map of node ID → CloudDOMNode for O(n) lookup
+     *
+     * Recursively walks the CloudDOM tree and collects all nodes.
+     *
+     * @param nodes - CloudDOM tree (root nodes)
+     * @returns Map of node ID → CloudDOMNode
+     */
+    buildNodeMap(nodes) {
+        const map = new Map();
+        const walk = (node) => {
+            map.set(node.id, node);
+            if (node.children && node.children.length > 0) {
+                node.children.forEach(walk);
+            }
+        };
+        nodes.forEach(walk);
+        return map;
+    }
+    /**
+     * Detect moves (nodes that changed parent in hierarchy)
+     *
+     * A move is detected when:
+     * - Node exists in both previous and current
+     * - Node's parent path changed (using array equality, not string comparison)
+     *
+     * This is useful for hierarchical updates where resources move
+     * between parent containers.
+     *
+     * @param previousMap - Previous node map
+     * @param currentMap - Current node map
+     * @returns Array of move operations with node ID
+     */
+    detectMoves(previousMap, currentMap) {
+        const moves = [];
+        for (const [id, currentNode] of currentMap) {
+            const previousNode = previousMap.get(id);
+            if (previousNode) {
+                // Get parent paths (all but last segment)
+                const prevParentPathArray = previousNode.path.slice(0, -1);
+                const currParentPathArray = currentNode.path.slice(0, -1);
+                // CRITICAL FIX: Handle empty parent paths (root nodes)
+                // Both nodes at root level (empty parent paths) - no move
+                if (prevParentPathArray.length === 0 && currParentPathArray.length === 0) {
+                    this.log(`Skipping move detection for root node: ${id}`);
+                    continue;
+                }
+                // Check if parent changed using array equality (not string comparison)
+                // This handles dynamic segments correctly
+                if (!(0, deepEqual_1.deepEqual)(prevParentPathArray, currParentPathArray, false)) {
+                    const prevParentPath = prevParentPathArray.join('.') || '<root>';
+                    const currParentPath = currParentPathArray.join('.') || '<root>';
+                    // Only add if paths are actually different strings
+                    if (prevParentPath !== currParentPath) {
+                        moves.push({
+                            nodeId: id,
+                            from: prevParentPath,
+                            to: currParentPath,
+                        });
+                        this.log(`Move detected: ${id} from ${prevParentPath} to ${currParentPath}`);
+                    }
+                }
+            }
+        }
+        return moves;
+    }
+    /**
+     * Detect the type of change between two nodes
+     *
+     * Returns:
+     * - 'replacement': Construct type changed (needs delete + create)
+     * - 'update': Props changed but construct is same (can update in place)
+     * - 'none': No changes detected
+     *
+     * Performance optimization:
+     * - Uses shallow prop hashes for O(1) comparison
+     * - Only falls back to deep equality if hashes differ
+     * - Caches hashes in node metadata (_propHash)
+     *
+     * NOTE: The `state` field is intentionally NOT compared during reconciliation.
+     * Only `props` and `outputs` are compared. The `state` field contains useState
+     * values which should not trigger infrastructure updates. This separation ensures
+     * that application state changes don't cause unnecessary resource deployments.
+     *
+     * @param previous - Previous node
+     * @param current - Current node
+     * @returns Change type
+     */
+    detectChangeType(previous, current) {
+        var _a, _b;
+        // Check if construct type changed (needs replacement)
+        // Use constructType string field for reliable comparison after serialization
+        const prevType = previous.constructType || this.getConstructName(previous.construct);
+        const currType = current.constructType || this.getConstructName(current.construct);
+        if (prevType !== currType) {
+            logger.debug(`Construct type mismatch for ${current.id}:`, {
+                previousType: prevType,
+                currentType: currType,
+            });
+            return 'replacement';
+        }
+        // Hash-based diff acceleration: compute or reuse cached hashes
+        const prevHash = ((_a = previous)._propHash ?? (_a._propHash = this.computeShallowHash(previous.props)));
+        const currHash = ((_b = current)._propHash ?? (_b._propHash = this.computeShallowHash(current.props)));
+        logger.debug(`Hash comparison for ${current.id}:`, {
+            prevHash,
+            currHash,
+            match: prevHash === currHash,
+            prevProps: previous.props,
+            currProps: current.props,
+        });
+        // Fast path: if hashes match, props are identical (skip deep equality)
+        if (prevHash === currHash) {
+            // Props are identical - no change needed
+            // NOTE: outputs are ignored per REQ-R03 (runtime values only)
+            return 'none';
+        }
+        // Hashes differ: perform deep equality check to confirm
+        // NOTE: Only compares `props` field, NOT `outputs` or `state` fields
+        // outputs are runtime values and should not trigger reconciliation (REQ-R03)
+        if (this.propsChanged(previous.props, current.props)) {
+            return 'update';
+        }
+        return 'none';
+    }
+    /**
+     * Check if two constructs are equal
+     *
+     * Constructs are considered equal if they have the same name.
+     * Handles edge cases like minified builds where function names may be undefined.
+     *
+     * NOTE: After serialization, construct field may be undefined, so we rely on
+     * constructType string field for comparison.
+     *
+     * @param a - First construct
+     * @param b - Second construct
+     * @returns True if constructs are equal
+     */
+    constructsEqual(a, b) {
+        // Handle null/undefined
+        if (a === b) {
+            return true;
+        }
+        if (!a || !b) {
+            return false;
+        }
+        // Extract names for comparison
+        const nameA = this.getConstructName(a);
+        const nameB = this.getConstructName(b);
+        return nameA === nameB;
+    }
+    /**
+     * Get the name of a construct
+     *
+     * @param construct - Construct to get name from
+     * @returns Construct name
+     */
+    getConstructName(construct) {
+        if (typeof construct === 'string') {
+            return construct;
+        }
+        if (typeof construct === 'function') {
+            return construct.name || construct.constructor?.name || 'anonymous';
+        }
+        if (construct && typeof construct === 'object' && 'name' in construct) {
+            return String(construct.name);
+        }
+        return 'unknown';
+    }
+    /**
+     * Check if node props have changed using deep equality
+     *
+     * Compares props objects deeply to detect any changes.
+     * Uses the deepEqual utility with memoization for performance.
+     *
+     * Excludes special props that don't affect rendering:
+     * - Metadata props (starting with _)
+     * - key prop (used for identity, not rendering)
+     * - children prop (handled separately in rendering)
+     *
+     * @param prevProps - Previous props (optional, defaults to empty object)
+     * @param currProps - Current props (optional, defaults to empty object)
+     * @returns True if props have changed
+     */
+    propsChanged(prevProps = {}, currProps = {}) {
+        // Filter out special props that don't affect rendering
+        const filterSpecialProps = (props) => {
+            const filtered = {};
+            for (const [key, value] of Object.entries(props)) {
+                // Exclude metadata (starts with _)
+                if (this.isMetadataKey(key)) {
+                    continue;
+                }
+                // Exclude key (used for identity, not rendering)
+                if (key === 'key') {
+                    continue;
+                }
+                // Exclude children (handled separately)
+                if (key === 'children') {
+                    continue;
+                }
+                filtered[key] = value;
+            }
+            return filtered;
+        };
+        const prevFiltered = filterSpecialProps(prevProps);
+        const currFiltered = filterSpecialProps(currProps);
+        // Use deep equality with memoization
+        return !(0, deepEqual_1.deepEqual)(prevFiltered, currFiltered);
+    }
+    /**
+     * Check if outputs have changed using deep equality
+     *
+     * Treats empty objects ({}) as equivalent to undefined for idempotency.
+     *
+     * NOTE: This method only receives and compares the `outputs` field from CloudDOMNode.
+     * The `state` field is never passed to this method, ensuring that useState values
+     * do not trigger infrastructure updates. This separation is automatic - callers
+     * explicitly pass `node.outputs`, not `node.state`.
+     *
+     * @param previous - Previous outputs (from node.outputs field only)
+     * @param current - Current outputs (from node.outputs field only)
+     * @returns True if outputs changed
+     */
+    outputsChanged(previous, current) {
+        // Helper to check if output is empty (undefined or {})
+        const isEmpty = (output) => {
+            return (output === undefined || (typeof output === 'object' && Object.keys(output).length === 0));
+        };
+        const prevIsEmpty = isEmpty(previous);
+        const currIsEmpty = isEmpty(current);
+        // CRITICAL FIX: Both empty - no change
+        if (prevIsEmpty && currIsEmpty) {
+            return false;
+        }
+        // One empty, one not - changed
+        if (prevIsEmpty !== currIsEmpty) {
+            return true;
+        }
+        // Both have content - use deep equality
+        return !(0, deepEqual_1.deepEqual)(previous, current, true);
+    }
+    /**
+     * Build dependency graph from CloudDOM nodes
+     *
+     * Scans node props for references to other node IDs and builds
+     * an adjacency list representing dependencies.
+     *
+     * A node depends on another if its props reference the other node's ID.
+     *
+     * REQ-O01: Dependency graph for deployment ordering
+     *
+     * @param nodes - CloudDOM nodes
+     * @returns DependencyGraph with adjacency lists
+     */
+    buildDependencyGraph(nodes) {
+        const dependencies = new Map();
+        const dependents = new Map();
+        // Initialize empty dependency lists for all nodes
+        for (const node of nodes) {
+            dependencies.set(node.id, []);
+            dependents.set(node.id, []);
+        }
+        // Build set of all node IDs for quick lookup
+        const nodeIds = new Set(nodes.map((n) => n.id));
+        // Scan props for references to other node IDs
+        for (const node of nodes) {
+            const deps = this.extractDependencies(node, nodeIds);
+            dependencies.set(node.id, deps);
+            // Build reverse adjacency list (dependents)
+            for (const depId of deps) {
+                if (!dependents.has(depId)) {
+                    dependents.set(depId, []);
+                }
+                dependents.get(depId).push(node.id);
+            }
+        }
+        // Validate graph integrity
+        this.validateGraph({ dependencies, dependents });
+        // Detect circular dependencies
+        this.detectCircularDependencies(dependencies);
+        return { dependencies, dependents };
+    }
+    /**
+     * Validate dependency graph integrity
+     *
+     * Ensures all dependencies exist in the graph and no missing node IDs remain.
+     *
+     * @param graph - Dependency graph to validate
+     * @throws ReconciliationError if graph is invalid
+     */
+    validateGraph(graph) {
+        const { dependencies } = graph;
+        for (const [nodeId, deps] of dependencies) {
+            for (const depId of deps) {
+                if (!dependencies.has(depId)) {
+                    const errorDetails = {
+                        nodeId,
+                        missingDependency: depId,
+                        availableNodes: Array.from(dependencies.keys()),
+                    };
+                    throw new errors_1.ReconciliationError(`Missing dependency: ${nodeId} → ${depId}. Referenced node does not exist in graph.`, errorDetails);
+                }
+            }
+        }
+    }
+    /**
+     * Extract dependencies from a node's props
+     *
+     * Recursively scans props object for strings that match other node IDs.
+     *
+     * Optimizations:
+     * - Skips props that start with underscore (internal metadata)
+     * - Uses explicit ref convention when available (props.ref or props.dependsOn)
+     * - Caches known non-ID props to avoid false positives
+     *
+     * @param node - CloudDOM node
+     * @param nodeIds - Set of all node IDs for validation
+     * @returns Array of dependency IDs
+     */
+    extractDependencies(node, nodeIds) {
+        const deps = new Set();
+        // Check for explicit dependency declarations first
+        if (node.props.dependsOn) {
+            const dependsOn = Array.isArray(node.props.dependsOn)
+                ? node.props.dependsOn
+                : [node.props.dependsOn];
+            for (const depId of dependsOn) {
+                if (typeof depId === 'string' && nodeIds.has(depId) && depId !== node.id) {
+                    deps.add(depId);
+                }
+            }
+        }
+        // Check for ref prop (common convention)
+        if (node.props.ref && typeof node.props.ref === 'string') {
+            if (nodeIds.has(node.props.ref) && node.props.ref !== node.id) {
+                deps.add(node.props.ref);
+            }
+        }
+        // Scan all props for implicit dependencies
+        const scan = (value, key) => {
+            // Skip internal metadata props using shared helper
+            if (key && this.isMetadataKey(key)) {
+                return;
+            }
+            // Skip known non-ID props
+            if (key && this.isKnownNonIdProp(key)) {
+                return;
+            }
+            if (typeof value === 'string') {
+                // Check if this string is a node ID
+                if (nodeIds.has(value) && value !== node.id) {
+                    deps.add(value);
+                }
+            }
+            else if (Array.isArray(value)) {
+                value.forEach((v) => scan(v));
+            }
+            else if (value && typeof value === 'object') {
+                for (const [k, v] of Object.entries(value)) {
+                    scan(v, k);
+                }
+            }
+        };
+        // Scan all props
+        for (const [key, value] of Object.entries(node.props)) {
+            scan(value, key);
+        }
+        return Array.from(deps);
+    }
+    /**
+     * Check if a prop key is known to never contain node IDs
+     *
+     * This helps avoid false positives in dependency extraction.
+     *
+     * @param key - Prop key
+     * @returns True if this prop is known to not contain IDs
+     */
+    isKnownNonIdProp(key) {
+        const knownNonIdProps = new Set([
+            'name',
+            'description',
+            'version',
+            'region',
+            'zone',
+            'namespace',
+            'label',
+            'tag',
+            'tags',
+            'metadata',
+            'annotations',
+            'key',
+        ]);
+        return knownNonIdProps.has(key);
+    }
+    /**
+     * Detect circular dependencies using DFS
+     *
+     * Collects all cycles before throwing to provide comprehensive diagnostics.
+     *
+     * REQ-O01: Circular dependency detection
+     *
+     * @param dependencies - Dependency adjacency list
+     * @throws ReconciliationError if circular dependencies are detected
+     */
+    detectCircularDependencies(dependencies) {
+        const visited = new Set();
+        const stack = new Set();
+        const cycles = [];
+        const dfs = (nodeId, path = []) => {
+            if (stack.has(nodeId)) {
+                // Circular dependency detected - collect it
+                const cycle = [...path, nodeId];
+                cycles.push(cycle);
+                return;
+            }
+            if (visited.has(nodeId)) {
+                return;
+            }
+            visited.add(nodeId);
+            stack.add(nodeId);
+            const deps = dependencies.get(nodeId) || [];
+            for (const depId of deps) {
+                try {
+                    dfs(depId, [...path, nodeId]);
+                }
+                catch {
+                    // Continue checking other dependencies
+                }
+            }
+            stack.delete(nodeId);
+        };
+        // Run DFS from each node to find all cycles
+        for (const nodeId of dependencies.keys()) {
+            if (!visited.has(nodeId)) {
+                dfs(nodeId);
+            }
+        }
+        // Throw if any cycles were found
+        if (cycles.length > 0) {
+            const cycleStrings = cycles.map((cycle) => cycle.join(' → '));
+            throw new errors_1.ReconciliationError(`Circular dependencies detected:\n  ${cycleStrings.join('\n  ')}`, {
+                cycles,
+                count: cycles.length,
+            });
+        }
+    }
+    /**
+     * Compute topological sort for deployment order using Kahn's algorithm
+     *
+     * Returns array of node IDs in deployment order (dependencies first).
+     * Nodes with same depth are sorted by ID for determinism.
+     *
+     * REQ-O01: Topological sort for deployment order
+     *
+     * @param graph - Dependency graph
+     * @returns Array of node IDs in deployment order
+     */
+    topologicalSort(graph) {
+        const { dependencies, dependents } = graph;
+        // Calculate in-degree for each node (number of dependencies)
+        const inDegree = new Map();
+        for (const [nodeId, deps] of dependencies) {
+            inDegree.set(nodeId, deps.length);
+        }
+        // Start with nodes that have no dependencies (in-degree = 0)
+        const queue = [];
+        for (const [nodeId, degree] of inDegree) {
+            if (degree === 0) {
+                queue.push(nodeId);
+            }
+        }
+        // Sort queue for determinism
+        queue.sort();
+        const result = [];
+        while (queue.length > 0) {
+            // Process nodes at same depth in sorted order for determinism
+            const batchSize = queue.length;
+            const batch = [];
+            for (let i = 0; i < batchSize; i++) {
+                const nodeId = queue.shift();
+                batch.push(nodeId);
+                // Reduce in-degree of dependents
+                const deps = dependents.get(nodeId) || [];
+                for (const depId of deps) {
+                    const degree = inDegree.get(depId) - 1;
+                    inDegree.set(depId, degree);
+                    if (degree === 0) {
+                        queue.push(depId);
+                    }
+                }
+            }
+            // Sort batch for determinism and add to result
+            batch.sort();
+            result.push(...batch);
+            // Sort queue for next iteration
+            queue.sort();
+        }
+        // Safety guard: ensure all nodes were sorted
+        if (result.length !== dependencies.size) {
+            throw new errors_1.ReconciliationError(`Topological sort incomplete: ${result.length}/${dependencies.size} nodes sorted. Possible cycle or missing dependency.`, {
+                sorted: result,
+                expected: dependencies.size,
+                missing: Array.from(dependencies.keys()).filter((id) => !result.includes(id)),
+            });
+        }
+        return result;
+    }
+    /**
+     * Compute parallel deployment batches
+     *
+     * Groups nodes by depth in dependency graph.
+     * Nodes at same depth can deploy in parallel (no dependencies between them).
+     *
+     * REQ-O01: Parallel deployment batches
+     *
+     * @param deploymentOrder - Topologically sorted node IDs
+     * @param graph - Dependency graph
+     * @returns Array of batches (each batch can deploy in parallel)
+     */
+    computeParallelBatches(deploymentOrder, graph) {
+        const { dependencies } = graph;
+        // Calculate depth for each node (max distance from a root node)
+        const depths = new Map();
+        for (const nodeId of deploymentOrder) {
+            const deps = dependencies.get(nodeId) || [];
+            if (deps.length === 0) {
+                // Root node (no dependencies)
+                depths.set(nodeId, 0);
+            }
+            else {
+                // Depth = max(dependency depths) + 1
+                const maxDepth = Math.max(...deps.map((depId) => depths.get(depId) || 0));
+                depths.set(nodeId, maxDepth + 1);
+            }
+        }
+        // Group nodes by depth
+        const batches = new Map();
+        for (const [nodeId, depth] of depths) {
+            if (!batches.has(depth)) {
+                batches.set(depth, []);
+            }
+            batches.get(depth).push(nodeId);
+        }
+        // Convert to array and sort each batch for determinism
+        const result = [];
+        const sortedDepths = Array.from(batches.keys()).sort((a, b) => a - b);
+        for (const depth of sortedDepths) {
+            const batch = batches.get(depth);
+            batch.sort(); // Sort for determinism
+            result.push(batch);
+        }
+        return result;
+    }
+}
+exports.Reconciler = Reconciler;