@olane/o-node 0.7.12-alpha.5 → 0.7.12-alpha.9

package/dist/src/interfaces/i-reconnectable-node.d.ts

@@ -0,0 +1,41 @@
+import { oAddress, NodeState, oNotificationManager } from '@olane/o-core';
+import { oNodeAddress } from '../router/o-node.address.js';
+import { oNodeConfig } from './o-node.config.js';
+/**
+ * Interface for nodes that support reconnection management.
+ * This interface defines the contract that oReconnectionManager needs
+ * to perform reconnection operations without creating a circular dependency.
+ */
+export interface IReconnectableNode {
+    /**
+     * The node's configuration
+     */
+    config: oNodeConfig;
+    /**
+     * The node's current address
+     */
+    address: oNodeAddress;
+    /**
+     * The node's current state
+     */
+    state: NodeState;
+    /**
+     * The notification manager for subscribing to events
+     */
+    notificationManager: oNotificationManager;
+    /**
+     * Register with the parent node
+     */
+    registerParent(): Promise<void>;
+    /**
+     * Execute a method on another node
+     */
+    use(address: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }): Promise<any>;
+}
+//# sourceMappingURL=i-reconnectable-node.d.ts.map

package/dist/src/interfaces/i-reconnectable-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i-reconnectable-node.d.ts","sourceRoot":"","sources":["../../../src/interfaces/i-reconnectable-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IAEjB;;OAEG;IACH,mBAAmB,EAAE,oBAAoB,CAAC;IAE1C;;OAEG;IACH,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhC;;OAEG;IACH,GAAG,CACD,OAAO,EAAE,QAAQ,EACjB,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAC;QAChC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GACA,OAAO,CAAC,GAAG,CAAC,CAAC;CACjB"}

package/dist/src/interfaces/i-reconnectable-node.js

@@ -0,0 +1 @@
+export {};

package/dist/src/interfaces/o-node.config.d.ts

@@ -3,5 +3,40 @@ import { oNodeAddress } from '../router/o-node.address.js';
 export interface oNodeConfig extends oCoreConfig {
     leader: oNodeAddress | null;
     parent: oNodeAddress | null;
+    /**
+     * Connection heartbeat configuration (libp2p-native pings)
+     * Detects dead connections via periodic pings using libp2p's ping service
+     */
+    connectionHeartbeat?: {
+        enabled?: boolean;
+        intervalMs?: number;
+        timeoutMs?: number;
+        failureThreshold?: number;
+        checkChildren?: boolean;
+        checkParent?: boolean;
+        checkLeader?: boolean;
+    };
+    /**
+     * Automatic reconnection configuration
+     * Handles parent connection failures and attempts to reconnect
+     */
+    reconnection?: {
+        enabled?: boolean;
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        useLeaderFallback?: boolean;
+    };
+    /**
+     * Leader request retry configuration
+     * Handles temporary leader unavailability (healing, maintenance)
+     */
+    leaderRetry?: {
+        enabled?: boolean;
+        maxAttempts?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        timeoutMs?: number;
+    };
 }
 //# sourceMappingURL=o-node.config.d.ts.map

package/dist/src/interfaces/o-node.config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.config.d.ts","sourceRoot":"","sources":["../../../src/interfaces/o-node.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;CAC7B"}
+{"version":3,"file":"o-node.config.d.ts","sourceRoot":"","sources":["../../../src/interfaces/o-node.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAE5B;;;OAGG;IACH,mBAAmB,CAAC,EAAE;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC;IAEF;;;OAGG;IACH,YAAY,CAAC,EAAE;QACb,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,CAAC;IAEF;;;OAGG;IACH,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH"}

package/dist/src/managers/o-connection-heartbeat.manager.d.ts

@@ -0,0 +1,67 @@
+import { Libp2p } from '@olane/o-config';
+import { oObject } from '@olane/o-core';
+import { oNodeAddress } from '../router/o-node.address.js';
+import { oNodeHierarchyManager } from '../o-node.hierarchy-manager.js';
+import { oNotificationManager } from '@olane/o-core';
+export interface HeartbeatConfig {
+    enabled: boolean;
+    intervalMs: number;
+    timeoutMs: number;
+    failureThreshold: number;
+    checkChildren: boolean;
+    checkParent: boolean;
+    checkLeader: boolean;
+}
+export interface ConnectionHealth {
+    address: oNodeAddress;
+    peerId: string;
+    lastSuccessfulPing: number;
+    consecutiveFailures: number;
+    averageLatency: number;
+    status: 'healthy' | 'degraded' | 'dead';
+}
+/**
+ * Connection Heartbeat Manager
+ *
+ * Uses libp2p's native ping service to detect dead connections early.
+ * Continuously pings parent and children to ensure they're alive.
+ *
+ * How it works:
+ * - Every `intervalMs`, pings all tracked connections
+ * - If ping fails, increments failure counter
+ * - After `failureThreshold` failures, marks connection as dead
+ * - Emits events for degraded/recovered/dead connections
+ * - Automatically removes dead children from hierarchy
+ * - Emits ParentDisconnectedEvent when parent dies (triggers reconnection)
+ */
+export declare class oConnectionHeartbeatManager extends oObject {
+    private p2pNode;
+    private hierarchyManager;
+    private notificationManager;
+    private address;
+    private config;
+    private heartbeatInterval?;
+    private healthMap;
+    constructor(p2pNode: Libp2p, hierarchyManager: oNodeHierarchyManager, notificationManager: oNotificationManager, address: oNodeAddress, config: HeartbeatConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private performHeartbeatCycle;
+    private pingTarget;
+    private handleConnectionDead;
+    private emitConnectionDegradedEvent;
+    private emitConnectionRecoveredEvent;
+    private extractPeerIdFromAddress;
+    /**
+     * Get current health status of all connections
+     */
+    getHealthStatus(): ConnectionHealth[];
+    /**
+     * Get health status for specific address
+     */
+    getConnectionHealth(address: oNodeAddress): ConnectionHealth | undefined;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HeartbeatConfig;
+}
+//# sourceMappingURL=o-connection-heartbeat.manager.d.ts.map

package/dist/src/managers/o-connection-heartbeat.manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-connection-heartbeat.manager.d.ts","sourceRoot":"","sources":["../../../src/managers/o-connection-heartbeat.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EACL,OAAO,EAMR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CACzC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,2BAA4B,SAAQ,OAAO;IAKpD,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,mBAAmB;IAC3B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IARhB,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAC3C,OAAO,CAAC,SAAS,CAAuC;gBAG9C,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,qBAAqB,EACvC,mBAAmB,EAAE,oBAAoB,EACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe;IAK3B,KAAK;IAqBL,IAAI;YAQI,qBAAqB;YAuCrB,UAAU;IAyFxB,OAAO,CAAC,oBAAoB;IAyD5B,OAAO,CAAC,2BAA2B;IAmBnC,OAAO,CAAC,4BAA4B;IAiBpC,OAAO,CAAC,wBAAwB;IAahC;;OAEG;IACH,eAAe,IAAI,gBAAgB,EAAE;IAIrC;;OAEG;IACH,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,GAAG,SAAS;IAIxE;;OAEG;IACH,SAAS,IAAI,eAAe;CAG7B"}

package/dist/src/managers/o-connection-heartbeat.manager.js

@@ -0,0 +1,223 @@
+import { oObject, ChildLeftEvent, ParentDisconnectedEvent, LeaderDisconnectedEvent, ConnectionDegradedEvent, ConnectionRecoveredEvent, } from '@olane/o-core';
+/**
+ * Connection Heartbeat Manager
+ *
+ * Uses libp2p's native ping service to detect dead connections early.
+ * Continuously pings parent and children to ensure they're alive.
+ *
+ * How it works:
+ * - Every `intervalMs`, pings all tracked connections
+ * - If ping fails, increments failure counter
+ * - After `failureThreshold` failures, marks connection as dead
+ * - Emits events for degraded/recovered/dead connections
+ * - Automatically removes dead children from hierarchy
+ * - Emits ParentDisconnectedEvent when parent dies (triggers reconnection)
+ */
+export class oConnectionHeartbeatManager extends oObject {
+    constructor(p2pNode, hierarchyManager, notificationManager, address, config) {
+        super();
+        this.p2pNode = p2pNode;
+        this.hierarchyManager = hierarchyManager;
+        this.notificationManager = notificationManager;
+        this.address = address;
+        this.config = config;
+        this.healthMap = new Map();
+    }
+    async start() {
+        if (!this.config.enabled) {
+            this.logger.debug('Connection heartbeat disabled');
+            return;
+        }
+        this.logger.info(`Starting connection heartbeat: interval=${this.config.intervalMs}ms, ` +
+            `timeout=${this.config.timeoutMs}ms, threshold=${this.config.failureThreshold}`);
+        // Immediate first check
+        await this.performHeartbeatCycle();
+        // Schedule recurring checks
+        this.heartbeatInterval = setInterval(() => this.performHeartbeatCycle(), this.config.intervalMs);
+    }
+    async stop() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = undefined;
+        }
+        this.healthMap.clear();
+    }
+    async performHeartbeatCycle() {
+        const targets = [];
+        // Check if this is a leader node (no leader in hierarchy = we are leader)
+        const isLeaderNode = this.hierarchyManager.getLeaders().length === 0;
+        // Collect leader (if enabled and we're not the leader)
+        if (this.config.checkLeader && !isLeaderNode) {
+            const leaders = this.hierarchyManager.getLeaders();
+            for (const leader of leaders) {
+                targets.push({ address: leader, role: 'leader' });
+            }
+        }
+        // Collect parent
+        if (this.config.checkParent && !isLeaderNode) {
+            const parents = this.hierarchyManager.getParents();
+            for (const parent of parents) {
+                targets.push({ address: parent, role: 'parent' });
+            }
+        }
+        // Collect children
+        if (this.config.checkChildren) {
+            const children = this.hierarchyManager.getChildren();
+            for (const child of children) {
+                targets.push({ address: child, role: 'child' });
+            }
+        }
+        // Ping all targets in parallel
+        await Promise.allSettled(targets.map((target) => this.pingTarget(target.address, target.role)));
+    }
+    async pingTarget(address, role) {
+        const peerId = this.extractPeerIdFromAddress(address);
+        if (!peerId) {
+            this.logger.warn(`Cannot extract peerId from ${address}`);
+            return;
+        }
+        const key = address.toString();
+        let health = this.healthMap.get(key);
+        if (!health) {
+            health = {
+                address,
+                peerId,
+                lastSuccessfulPing: 0,
+                consecutiveFailures: 0,
+                averageLatency: 0,
+                status: 'healthy',
+            };
+            this.healthMap.set(key, health);
+        }
+        try {
+            // Use libp2p's native ping service
+            const startTime = Date.now();
+            // Create timeout promise
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('Ping timeout')), this.config.timeoutMs);
+            });
+            // Race between ping and timeout
+            // The ping service accepts PeerId as string or object
+            await Promise.race([
+                this.p2pNode.services.ping.ping(peerId),
+                timeoutPromise,
+            ]);
+            const latency = Date.now() - startTime;
+            // Success - update health
+            health.lastSuccessfulPing = Date.now();
+            health.consecutiveFailures = 0;
+            health.averageLatency =
+                health.averageLatency === 0
+                    ? latency
+                    : health.averageLatency * 0.7 + latency * 0.3; // Exponential moving average
+            const previousStatus = health.status;
+            health.status = 'healthy';
+            // Emit recovery event if was degraded
+            if (previousStatus === 'degraded') {
+                this.logger.info(`Connection recovered: ${address} (latency: ${latency}ms)`);
+                this.emitConnectionRecoveredEvent(address, role);
+            }
+            this.logger.debug(`Ping successful: ${address} (${latency}ms)`);
+        }
+        catch (error) {
+            health.consecutiveFailures++;
+            this.logger.warn(`Ping failed: ${address} (failures: ${health.consecutiveFailures}/${this.config.failureThreshold})`);
+            // Update status based on failure count
+            if (health.consecutiveFailures >= this.config.failureThreshold) {
+                this.handleConnectionDead(address, role, health);
+            }
+            else if (health.consecutiveFailures >= Math.ceil(this.config.failureThreshold / 2)) {
+                health.status = 'degraded';
+                this.emitConnectionDegradedEvent(address, role, health.consecutiveFailures);
+            }
+        }
+    }
+    handleConnectionDead(address, role, health) {
+        health.status = 'dead';
+        this.logger.error(`Connection dead after ${health.consecutiveFailures} failures: ${address} (role: ${role})`);
+        // Remove from health tracking
+        this.healthMap.delete(address.toString());
+        // Emit events based on role
+        if (role === 'child') {
+            // Remove dead child from hierarchy
+            this.hierarchyManager.removeChild(address);
+            // Emit child left event
+            this.notificationManager.emit(new ChildLeftEvent({
+                source: this.address,
+                childAddress: address,
+                parentAddress: this.address,
+                reason: `heartbeat_failed_${health.consecutiveFailures}_times`,
+            }));
+            this.logger.warn(`Removed dead child: ${address}`);
+        }
+        else if (role === 'parent') {
+            // Emit parent disconnected event
+            this.notificationManager.emit(new ParentDisconnectedEvent({
+                source: this.address,
+                parentAddress: address,
+                reason: `heartbeat_failed_${health.consecutiveFailures}_times`,
+            }));
+            this.logger.error(`Parent connection dead: ${address}`);
+            // Reconnection manager will handle this event
+        }
+        else if (role === 'leader') {
+            // Emit leader disconnected event
+            this.notificationManager.emit(new LeaderDisconnectedEvent({
+                source: this.address,
+                leaderAddress: address,
+                reason: `heartbeat_failed_${health.consecutiveFailures}_times`,
+            }));
+            this.logger.error(`Leader connection dead: ${address}`);
+            // Reconnection manager will handle this event
+        }
+    }
+    emitConnectionDegradedEvent(address, role, failures) {
+        // ConnectionDegradedEvent only supports parent/child, so we map leader to parent
+        const eventRole = role === 'leader' ? 'parent' : role === 'child' ? 'child' : 'parent';
+        this.notificationManager.emit(new ConnectionDegradedEvent({
+            source: this.address,
+            targetAddress: address,
+            role: eventRole,
+            consecutiveFailures: failures,
+        }));
+    }
+    emitConnectionRecoveredEvent(address, role) {
+        // ConnectionRecoveredEvent only supports parent/child, so we map leader to parent
+        const eventRole = role === 'leader' ? 'parent' : role === 'child' ? 'child' : 'parent';
+        this.notificationManager.emit(new ConnectionRecoveredEvent({
+            source: this.address,
+            targetAddress: address,
+            role: eventRole,
+        }));
+    }
+    extractPeerIdFromAddress(address) {
+        // Extract peerId from transport multiaddr
+        for (const transport of address.transports) {
+            const multiaddr = transport.toString();
+            // Multiaddr format: /ip4/127.0.0.1/tcp/4001/p2p/QmPeerId
+            const parts = multiaddr.split('/p2p/');
+            if (parts.length === 2) {
+                return parts[1];
+            }
+        }
+        return null;
+    }
+    /**
+     * Get current health status of all connections
+     */
+    getHealthStatus() {
+        return Array.from(this.healthMap.values());
+    }
+    /**
+     * Get health status for specific address
+     */
+    getConnectionHealth(address) {
+        return this.healthMap.get(address.toString());
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}

package/dist/src/managers/o-reconnection.manager.d.ts

@@ -0,0 +1,39 @@
+import { oObject } from '@olane/o-core';
+import { IReconnectableNode } from '../interfaces/i-reconnectable-node.js';
+export interface ReconnectionConfig {
+    enabled: boolean;
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    useLeaderFallback: boolean;
+}
+/**
+ * Reconnection Manager
+ *
+ * Automatically attempts to reconnect to parent when connection is lost.
+ *
+ * Strategy:
+ * 1. Listen for ParentDisconnectedEvent (from heartbeat or libp2p)
+ * 2. Attempt direct reconnection with exponential backoff
+ * 3. If direct reconnection fails, query leader for new parent
+ * 4. Register with new parent and continue operation
+ * 5. If all attempts fail, transition node to ERROR state
+ */
+export declare class oReconnectionManager extends oObject {
+    private node;
+    private config;
+    private reconnecting;
+    constructor(node: IReconnectableNode, config: ReconnectionConfig);
+    private setupEventListeners;
+    private handleConnectionDegraded;
+    private handleLeaderDisconnected;
+    private handleParentDisconnected;
+    attemptReconnection(): Promise<void>;
+    private tryDirectParentReconnection;
+    private tryLeaderFallback;
+    private handleReconnectionFailure;
+    private calculateNodeLevel;
+    private calculateBackoffDelay;
+    private sleep;
+}
+//# sourceMappingURL=o-reconnection.manager.d.ts.map

package/dist/src/managers/o-reconnection.manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-reconnection.manager.d.ts","sourceRoot":"","sources":["../../../src/managers/o-reconnection.manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAQR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAI3E,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IAI7C,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,MAAM;IAJhB,OAAO,CAAC,YAAY,CAAS;gBAGnB,IAAI,EAAE,kBAAkB,EACxB,MAAM,EAAE,kBAAkB;IAMpC,OAAO,CAAC,mBAAmB;YAoBb,wBAAwB;YAaxB,wBAAwB;YAexB,wBAAwB;IAehC,mBAAmB;YAkDX,2BAA2B;YAiB3B,iBAAiB;IAyC/B,OAAO,CAAC,yBAAyB;IAajC,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,KAAK;CAGd"}

package/dist/src/managers/o-reconnection.manager.js

@@ -0,0 +1,150 @@
+import { oObject, oAddress, NodeState, } from '@olane/o-core';
+import { oNodeAddress } from '../router/o-node.address.js';
+import { oNodeTransport } from '../router/o-node.transport.js';
+/**
+ * Reconnection Manager
+ *
+ * Automatically attempts to reconnect to parent when connection is lost.
+ *
+ * Strategy:
+ * 1. Listen for ParentDisconnectedEvent (from heartbeat or libp2p)
+ * 2. Attempt direct reconnection with exponential backoff
+ * 3. If direct reconnection fails, query leader for new parent
+ * 4. Register with new parent and continue operation
+ * 5. If all attempts fail, transition node to ERROR state
+ */
+export class oReconnectionManager extends oObject {
+    constructor(node, config) {
+        super();
+        this.node = node;
+        this.config = config;
+        this.reconnecting = false;
+        this.setupEventListeners();
+    }
+    setupEventListeners() {
+        // Listen for parent disconnection (from heartbeat or libp2p)
+        this.node.notificationManager.on('parent:disconnected', this.handleParentDisconnected.bind(this));
+        // Listen for leader disconnection (from heartbeat)
+        this.node.notificationManager.on('leader:disconnected', this.handleLeaderDisconnected.bind(this));
+        // Listen for connection degradation as early warning
+        this.node.notificationManager.on('connection:degraded', this.handleConnectionDegraded.bind(this));
+    }
+    async handleConnectionDegraded(event) {
+        const degradedEvent = event;
+        if (degradedEvent.role !== 'parent')
+            return;
+        this.logger.warn(`Parent connection degraded: ${degradedEvent.targetAddress} ` +
+            `(failures: ${degradedEvent.consecutiveFailures})`);
+        // Could implement pre-emptive parent discovery here
+        // For now, just log the warning and wait for full disconnection
+    }
+    async handleLeaderDisconnected(event) {
+        const disconnectEvent = event;
+        this.logger.warn(`Leader disconnected: ${disconnectEvent.leaderAddress} (reason: ${disconnectEvent.reason})`);
+        // Don't attempt reconnection for leader - the LeaderRequestWrapper
+        // will handle retries automatically when we make requests
+        // Just log the event for observability
+        this.logger.info('Leader requests will use automatic retry mechanism (LeaderRequestWrapper)');
+    }
+    async handleParentDisconnected(event) {
+        const disconnectEvent = event;
+        if (this.reconnecting) {
+            this.logger.debug('Already reconnecting, ignoring duplicate event');
+            return;
+        }
+        this.logger.warn(`Parent disconnected: ${disconnectEvent.parentAddress} (reason: ${disconnectEvent.reason})`);
+        await this.attemptReconnection();
+    }
+    async attemptReconnection() {
+        if (!this.config.enabled) {
+            this.logger.warn('Reconnection disabled - node will remain disconnected');
+            return;
+        }
+        this.reconnecting = true;
+        let attempt = 0;
+        while (attempt < this.config.maxAttempts) {
+            attempt++;
+            this.logger.info(`Reconnection attempt ${attempt}/${this.config.maxAttempts} to parent: ${this.node.config.parent}`);
+            try {
+                // Strategy 1: Try direct parent reconnection
+                await this.tryDirectParentReconnection();
+                // Success!
+                this.reconnecting = false;
+                this.logger.info(`Successfully reconnected to parent after ${attempt} attempts`);
+                return;
+            }
+            catch (error) {
+                this.logger.warn(`Reconnection attempt ${attempt} failed:`, error instanceof Error ? error.message : error);
+                if (attempt < this.config.maxAttempts) {
+                    const delay = this.calculateBackoffDelay(attempt);
+                    this.logger.debug(`Waiting ${delay}ms before next attempt...`);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All direct attempts failed - try leader fallback
+        if (this.config.useLeaderFallback) {
+            await this.tryLeaderFallback();
+        }
+        else {
+            this.handleReconnectionFailure();
+        }
+    }
+    async tryDirectParentReconnection() {
+        if (!this.node.config.parent) {
+            throw new Error('No parent configured');
+        }
+        // Re-register with parent (might have new transports)
+        await this.node.registerParent();
+        // Verify connection works with a ping
+        await this.node.use(this.node.config.parent, {
+            method: 'ping',
+            params: {},
+        });
+        this.logger.info('Direct parent reconnection successful');
+    }
+    async tryLeaderFallback() {
+        this.logger.info('Attempting leader fallback to find new parent');
+        try {
+            // Query registry for available parents at our level
+            const response = await this.node.use(new oAddress('o://registry'), {
+                method: 'find_available_parent',
+                params: {
+                    currentAddress: this.node.address.toString(),
+                    preferredLevel: this.calculateNodeLevel(),
+                },
+            });
+            const { parentAddress, parentTransports } = response.result.data;
+            if (parentAddress && parentTransports) {
+                // Update parent reference
+                this.node.config.parent = new oNodeAddress(parentAddress, parentTransports.map((t) => new oNodeTransport(t)));
+                // Register with new parent
+                await this.tryDirectParentReconnection();
+                this.reconnecting = false;
+                this.logger.info(`Successfully reconnected via new parent: ${parentAddress}`);
+                return;
+            }
+        }
+        catch (error) {
+            this.logger.error('Leader fallback failed:', error instanceof Error ? error.message : error);
+        }
+        this.handleReconnectionFailure();
+    }
+    handleReconnectionFailure() {
+        this.reconnecting = false;
+        this.logger.error('Failed to reconnect to parent after all attempts - node in ERROR state');
+        // Transition to error state
+        this.node.state = NodeState.ERROR;
+        // Could emit custom event here for monitoring
+    }
+    calculateNodeLevel() {
+        return this.node.address.paths.length;
+    }
+    calculateBackoffDelay(attempt) {
+        const delay = this.config.baseDelayMs * Math.pow(2, attempt - 1);
+        return Math.min(delay, this.config.maxDelayMs);
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/src/o-node.d.ts

@@ -3,11 +3,14 @@ import { PeerId } from '@olane/o-config';
 import { oNodeHierarchyManager } from './o-node.hierarchy-manager.js';
 import { oNodeConfig } from './interfaces/o-node.config.js';
 import { oNodeTransport } from './router/o-node.transport.js';
-import { oRequest } from '@olane/o-core';
+import { oAddress, oRequest, oNotificationManager } from '@olane/o-core';
 import { oNodeAddress } from './router/o-node.address.js';
 import { oNodeConnection } from './connection/o-node-connection.js';
 import { oNodeConnectionManager } from './connection/o-node-connection.manager.js';
 import { oToolBase } from '@olane/o-tool';
+import { oConnectionHeartbeatManager } from './managers/o-connection-heartbeat.manager.js';
+import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LeaderRequestWrapper } from './utils/leader-request-wrapper.js';
 export declare class oNode extends oToolBase {
     peerId: PeerId;
     p2pNode: Libp2p;
@@ -15,6 +18,9 @@ export declare class oNode extends oToolBase {
     config: oNodeConfig;
     connectionManager: oNodeConnectionManager;
     hierarchyManager: oNodeHierarchyManager;
+    connectionHeartbeatManager?: oConnectionHeartbeatManager;
+    reconnectionManager?: oReconnectionManager;
+    leaderRequestWrapper: LeaderRequestWrapper;
     protected didRegister: boolean;
     constructor(config: oNodeConfig);
     get leader(): oNodeAddress | null;
@@ -22,6 +28,7 @@ export declare class oNode extends oToolBase {
     get parentPeerId(): string | null;
     configureTransports(): any[];
     initializeRouter(): Promise<void>;
+    protected createNotificationManager(): oNotificationManager;
     get staticAddress(): oNodeAddress;
     get parentTransports(): oNodeTransport[];
     get transports(): oNodeTransport[];
@@ -39,6 +46,16 @@ export declare class oNode extends oToolBase {
     protected createNode(): Promise<Libp2p>;
     connect(nextHopAddress: oNodeAddress, targetAddress: oNodeAddress): Promise<oNodeConnection>;
     initialize(): Promise<void>;
+    /**
+     * Override use() to wrap leader/registry requests with retry logic
+     */
+    use(address: oAddress, data?: {
+        method?: string;
+        params?: {
+            [key: string]: any;
+        };
+        id?: string;
+    }): Promise<any>;
     teardown(): Promise<void>;
 }
 //# sourceMappingURL=o-node.d.ts.map

package/dist/src/o-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAKL,QAAQ,EAET,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAGnF,OAAO,EAAmB,SAAS,EAAE,MAAM,eAAe,CAAC;AAI3D,qBAAa,KAAM,SAAQ,SAAS;IAC3B,MAAM,EAAG,MAAM,CAAC;IAChB,OAAO,EAAG,MAAM,CAAC;IACjB,OAAO,EAAG,YAAY,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,iBAAiB,EAAG,sBAAsB,CAAC;IAC3C,gBAAgB,EAAG,qBAAqB,CAAC;IAChD,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;gBAE3B,MAAM,EAAE,WAAW;IAK/B,IAAI,MAAM,IAAI,YAAY,GAAG,IAAI,CAEhC;IAED,IAAI,aAAa,IAAI,YAAY,CAKhC;IAED,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAOhC;IAED,mBAAmB,IAAI,GAAG,EAAE;IAItB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC,IAAI,aAAa,IAAI,YAAY,CAEhC;IAED,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAEvC;IAED,IAAI,UAAU,IAAI,cAAc,EAAE,CAIjC;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC/B,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAG1D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;cA0FxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvC,OAAO,CACX,cAAc,EAAE,YAAY,EAC5B,aAAa,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC;IA0BrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAOhC"}
+{"version":3,"file":"o-node.d.ts","sourceRoot":"","sources":["../../src/o-node.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,YAAY,EACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAIL,QAAQ,EACR,QAAQ,EAER,oBAAoB,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAGnF,OAAO,EAAmB,SAAS,EAAE,MAAM,eAAe,CAAC;AAI3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,8CAA8C,CAAC;AAC3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,qBAAa,KAAM,SAAQ,SAAS;IAC3B,MAAM,EAAG,MAAM,CAAC;IAChB,OAAO,EAAG,MAAM,CAAC;IACjB,OAAO,EAAG,YAAY,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB,iBAAiB,EAAG,sBAAsB,CAAC;IAC3C,gBAAgB,EAAG,qBAAqB,CAAC;IACzC,0BAA0B,CAAC,EAAE,2BAA2B,CAAC;IACzD,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C,oBAAoB,EAAG,oBAAoB,CAAC;IACnD,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;gBAE3B,MAAM,EAAE,WAAW;IAK/B,IAAI,MAAM,IAAI,YAAY,GAAG,IAAI,CAEhC;IAED,IAAI,aAAa,IAAI,YAAY,CAKhC;IAED,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,CAOhC;IAED,mBAAmB,IAAI,GAAG,EAAE;IAItB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC,SAAS,CAAC,yBAAyB,IAAI,oBAAoB;IAQ3D,IAAI,aAAa,IAAI,YAAY,CAEhC;IAED,IAAI,gBAAgB,IAAI,cAAc,EAAE,CAEvC;IAED,IAAI,UAAU,IAAI,cAAc,EAAE,CAIjC;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAsD3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC/B,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAItC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAetB,mBAAmB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAG1D;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;cA0FxB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvC,OAAO,CACX,cAAc,EAAE,YAAY,EAC5B,aAAa,EAAE,YAAY,GAC1B,OAAO,CAAC,eAAe,CAAC;IA0BrB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2FjC;;OAEG;IACG,GAAG,CACP,OAAO,EAAE,QAAQ,EACjB,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE;YAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;SAAE,CAAC;QAChC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GACA,OAAO,CAAC,GAAG,CAAC;IAST,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAYhC"}

package/dist/src/o-node.js

@@ -9,6 +9,10 @@ import { oNodeConnectionManager } from './connection/o-node-connection.manager.j
 import { oNodeResolver } from './router/resolvers/o-node.resolver.js';
 import { oMethodResolver, oToolBase } from '@olane/o-tool';
 import { oLeaderResolverFallback } from './router/index.js';
+import { oNodeNotificationManager } from './o-node.notification-manager.js';
+import { oConnectionHeartbeatManager } from './managers/o-connection-heartbeat.manager.js';
+import { oReconnectionManager } from './managers/o-reconnection.manager.js';
+import { LeaderRequestWrapper } from './utils/leader-request-wrapper.js';
 export class oNode extends oToolBase {
     constructor(config) {
         super(config);
@@ -43,6 +47,9 @@ export class oNode extends oToolBase {
         });
         this.router = new oNodeRouter();
     }
+    createNotificationManager() {
+        return new oNodeNotificationManager(this.p2pNode, this.hierarchyManager, this.address);
+    }
     get staticAddress() {
         return this.config.address;
     }
@@ -60,6 +67,30 @@ export class oNode extends oToolBase {
             this.logger.debug('Skipping unregistration, node is leader');
             return;
         }
+        // Notify parent we're stopping (best-effort, 2s timeout)
+        if (this.config.parent) {
+            try {
+                await Promise.race([
+                    this.use(this.config.parent, {
+                        method: 'notify',
+                        params: {
+                            eventType: 'node:stopping',
+                            eventData: {
+                                address: this.address.toString(),
+                                reason: 'graceful_shutdown',
+                                expectedDowntime: null,
+                            },
+                            source: this.address.toString(),
+                        },
+                    }),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000)),
+                ]);
+                this.logger.debug('Notified parent of shutdown');
+            }
+            catch (error) {
+                this.logger.warn('Failed to notify parent (will be detected by heartbeat):', error instanceof Error ? error.message : error);
+            }
+        }
         if (!this.config.leader) {
             this.logger.debug('No leader found, skipping unregistration');
             return;
@@ -136,6 +167,10 @@ export class oNode extends oToolBase {
     }
     async start() {
         await super.start();
+        // Start heartbeat after node is running
+        if (this.connectionHeartbeatManager) {
+            await this.connectionHeartbeatManager.start();
+        }
         // await NetworkUtils.advertiseToNetwork(
         //   this.address,
         //   this.staticAddress,
@@ -256,6 +291,8 @@ export class oNode extends oToolBase {
         }
         await this.createNode();
         await this.initializeRouter();
+        // need to wait until our libpp2 node is initialized before calling super.initialize
+        await super.initialize();
         this.logger.debug('Node initialized!', this.transports.map((t) => t.toString()));
         this.address.setTransports(this.transports);
         this.peerId = this.p2pNode.peerId;
@@ -263,6 +300,16 @@ export class oNode extends oToolBase {
         this.connectionManager = new oNodeConnectionManager({
             p2pNode: this.p2pNode,
         });
+        // Initialize leader request wrapper
+        this.leaderRequestWrapper = new LeaderRequestWrapper({
+            enabled: this.config.leaderRetry?.enabled ?? true,
+            maxAttempts: this.config.leaderRetry?.maxAttempts ?? 20,
+            baseDelayMs: this.config.leaderRetry?.baseDelayMs ?? 2000,
+            maxDelayMs: this.config.leaderRetry?.maxDelayMs ?? 30000,
+            timeoutMs: this.config.leaderRetry?.timeoutMs ?? 10000,
+        });
+        this.logger.info(`Leader retry config: enabled=${this.leaderRequestWrapper.getConfig().enabled}, ` +
+            `maxAttempts=${this.leaderRequestWrapper.getConfig().maxAttempts}`);
         // initialize address resolution
         this.router.addResolver(new oMethodResolver(this.address));
         this.router.addResolver(new oNodeResolver(this.address));
@@ -271,8 +318,43 @@ export class oNode extends oToolBase {
             this.logger.debug('Adding leader resolver fallback...');
             this.router.addResolver(new oLeaderResolverFallback(this.address));
         }
+        // Read ENABLE_LEADER_HEARTBEAT environment variable
+        const enableLeaderHeartbeat = process.env.ENABLE_LEADER_HEARTBEAT === 'true';
+        // Initialize connection heartbeat manager
+        this.connectionHeartbeatManager = new oConnectionHeartbeatManager(this.p2pNode, this.hierarchyManager, this.notificationManager, this.address, {
+            enabled: this.config.connectionHeartbeat?.enabled ?? true,
+            intervalMs: this.config.connectionHeartbeat?.intervalMs ?? 15000,
+            timeoutMs: this.config.connectionHeartbeat?.timeoutMs ?? 5000,
+            failureThreshold: this.config.connectionHeartbeat?.failureThreshold ?? 3,
+            checkChildren: this.config.connectionHeartbeat?.checkChildren ?? true,
+            checkParent: this.config.connectionHeartbeat?.checkParent ?? true,
+            checkLeader: this.config.connectionHeartbeat?.checkLeader ?? enableLeaderHeartbeat,
+        });
+        this.logger.info(`Connection heartbeat config: leader=${this.connectionHeartbeatManager.getConfig().checkLeader}, ` +
+            `parent=${this.connectionHeartbeatManager.getConfig().checkParent}`);
+        // Initialize reconnection manager
+        if (this.config.reconnection?.enabled !== false) {
+            this.reconnectionManager = new oReconnectionManager(this, {
+                enabled: true,
+                maxAttempts: this.config.reconnection?.maxAttempts ?? 10,
+                baseDelayMs: this.config.reconnection?.baseDelayMs ?? 5000,
+                maxDelayMs: this.config.reconnection?.maxDelayMs ?? 60000,
+                useLeaderFallback: this.config.reconnection?.useLeaderFallback ?? true,
+            });
+        }
+    }
+    /**
+     * Override use() to wrap leader/registry requests with retry logic
+     */
+    async use(address, data) {
+        // Wrap leader/registry requests with retry logic
+        return this.leaderRequestWrapper.execute(() => super.use(address, data), address, data?.method);
     }
     async teardown() {
+        // Stop heartbeat before parent teardown
+        if (this.connectionHeartbeatManager) {
+            await this.connectionHeartbeatManager.stop();
+        }
         await this.unregister();
         await super.teardown();
         if (this.p2pNode) {

package/dist/src/o-node.notification-manager.d.ts

@@ -0,0 +1,52 @@
+import { Libp2p } from '@olane/o-config';
+import { oNotificationManager } from '@olane/o-core';
+import { oNodeAddress } from './router/o-node.address.js';
+import { oNodeHierarchyManager } from './o-node.hierarchy-manager.js';
+/**
+ * libp2p-specific implementation of oNotificationManager
+ * Wraps libp2p events and enriches them with Olane context
+ */
+export declare class oNodeNotificationManager extends oNotificationManager {
+    private p2pNode;
+    private hierarchyManager;
+    private address;
+    constructor(p2pNode: Libp2p, hierarchyManager: oNodeHierarchyManager, address: oNodeAddress);
+    /**
+     * Wire up libp2p event listeners
+     */
+    protected setupListeners(): void;
+    /**
+     * Handle peer connect event from libp2p
+     */
+    private handlePeerConnect;
+    /**
+     * Handle peer disconnect event from libp2p
+     */
+    private handlePeerDisconnect;
+    /**
+     * Handle peer discovery event from libp2p
+     */
+    private handlePeerDiscovery;
+    /**
+     * Handle connection open event from libp2p
+     */
+    private handleConnectionOpen;
+    /**
+     * Handle connection close event from libp2p
+     */
+    private handleConnectionClose;
+    /**
+     * Try to resolve a libp2p peer ID to an Olane address
+     * Checks hierarchy manager for known peers
+     */
+    private peerIdToAddress;
+    /**
+     * Check if an address is a direct child
+     */
+    private isChild;
+    /**
+     * Check if an address is a parent
+     */
+    private isParent;
+}
+//# sourceMappingURL=o-node.notification-manager.d.ts.map

package/dist/src/o-node.notification-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"o-node.notification-manager.d.ts","sourceRoot":"","sources":["../../src/o-node.notification-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EACL,oBAAoB,EAQrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;GAGG;AACH,qBAAa,wBAAyB,SAAQ,oBAAoB;IAE9D,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,OAAO;gBAFP,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,qBAAqB,EACvC,OAAO,EAAE,YAAY;IAK/B;;OAEG;IACH,SAAS,CAAC,cAAc,IAAI,IAAI;IAiBhC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgDzB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkD5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAmB3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAkCvB;;OAEG;IACH,OAAO,CAAC,OAAO;IAMf;;OAEG;IACH,OAAO,CAAC,QAAQ;CAKjB"}

package/dist/src/o-node.notification-manager.js

@@ -0,0 +1,183 @@
+import { oNotificationManager, NodeConnectedEvent, NodeDisconnectedEvent, NodeDiscoveredEvent, ChildJoinedEvent, ChildLeftEvent, ParentConnectedEvent, ParentDisconnectedEvent, } from '@olane/o-core';
+/**
+ * libp2p-specific implementation of oNotificationManager
+ * Wraps libp2p events and enriches them with Olane context
+ */
+export class oNodeNotificationManager extends oNotificationManager {
+    constructor(p2pNode, hierarchyManager, address) {
+        super();
+        this.p2pNode = p2pNode;
+        this.hierarchyManager = hierarchyManager;
+        this.address = address;
+    }
+    /**
+     * Wire up libp2p event listeners
+     */
+    setupListeners() {
+        this.logger.debug('Setting up libp2p event listeners...');
+        // Peer connection events
+        this.p2pNode.addEventListener('peer:connect', this.handlePeerConnect.bind(this));
+        this.p2pNode.addEventListener('peer:disconnect', this.handlePeerDisconnect.bind(this));
+        // Peer discovery events
+        this.p2pNode.addEventListener('peer:discovery', this.handlePeerDiscovery.bind(this));
+        // Connection events
+        this.p2pNode.addEventListener('connection:open', this.handleConnectionOpen.bind(this));
+        this.p2pNode.addEventListener('connection:close', this.handleConnectionClose.bind(this));
+        this.logger.debug('libp2p event listeners configured');
+    }
+    /**
+     * Handle peer connect event from libp2p
+     */
+    handlePeerConnect(evt) {
+        const peerId = evt.detail;
+        this.logger.debug(`Peer connected: ${peerId.toString()}`);
+        // Try to resolve peer ID to Olane address
+        const nodeAddress = this.peerIdToAddress(peerId.toString());
+        if (!nodeAddress) {
+            this.logger.debug(`Could not resolve peer ID ${peerId.toString()} to address`);
+            return;
+        }
+        // Emit generic node connected event
+        this.emit(new NodeConnectedEvent({
+            source: this.address,
+            nodeAddress,
+            connectionMetadata: {
+                peerId: peerId.toString(),
+                transport: 'libp2p',
+            },
+        }));
+        // Check if this is a child node
+        if (this.isChild(nodeAddress)) {
+            this.logger.debug(`Child node connected: ${nodeAddress.toString()}`);
+            this.emit(new ChildJoinedEvent({
+                source: this.address,
+                childAddress: nodeAddress,
+                parentAddress: this.address,
+            }));
+        }
+        // Check if this is a parent node
+        if (this.isParent(nodeAddress)) {
+            this.logger.debug(`Parent node connected: ${nodeAddress.toString()}`);
+            this.emit(new ParentConnectedEvent({
+                source: this.address,
+                parentAddress: nodeAddress,
+            }));
+        }
+    }
+    /**
+     * Handle peer disconnect event from libp2p
+     */
+    handlePeerDisconnect(evt) {
+        const peerId = evt.detail;
+        this.logger.debug(`Peer disconnected: ${peerId.toString()}`);
+        // Try to resolve peer ID to Olane address
+        const nodeAddress = this.peerIdToAddress(peerId.toString());
+        if (!nodeAddress) {
+            this.logger.debug(`Could not resolve peer ID ${peerId.toString()} to address`);
+            return;
+        }
+        // Emit generic node disconnected event
+        this.emit(new NodeDisconnectedEvent({
+            source: this.address,
+            nodeAddress,
+            reason: 'peer_disconnected',
+        }));
+        // Check if this is a child node
+        if (this.isChild(nodeAddress)) {
+            this.logger.debug(`Child node disconnected: ${nodeAddress.toString()}`);
+            this.emit(new ChildLeftEvent({
+                source: this.address,
+                childAddress: nodeAddress,
+                parentAddress: this.address,
+                reason: 'peer_disconnected',
+            }));
+            // Optionally remove from hierarchy (auto-cleanup)
+            // this.hierarchyManager.removeChild(nodeAddress);
+        }
+        // Check if this is a parent node
+        if (this.isParent(nodeAddress)) {
+            this.logger.debug(`Parent node disconnected: ${nodeAddress.toString()}`);
+            this.emit(new ParentDisconnectedEvent({
+                source: this.address,
+                parentAddress: nodeAddress,
+                reason: 'peer_disconnected',
+            }));
+        }
+    }
+    /**
+     * Handle peer discovery event from libp2p
+     */
+    handlePeerDiscovery(evt) {
+        const peerInfo = evt.detail;
+        this.logger.debug(`Peer discovered: ${peerInfo.id.toString()}`);
+        // Try to resolve peer ID to Olane address
+        const nodeAddress = this.peerIdToAddress(peerInfo.id.toString());
+        if (!nodeAddress) {
+            return;
+        }
+        this.emit(new NodeDiscoveredEvent({
+            source: this.address,
+            nodeAddress,
+        }));
+    }
+    /**
+     * Handle connection open event from libp2p
+     */
+    handleConnectionOpen(evt) {
+        const remotePeer = evt.detail.remotePeer;
+        this.logger.debug(`Connection opened to: ${remotePeer.toString()}`);
+    }
+    /**
+     * Handle connection close event from libp2p
+     */
+    handleConnectionClose(evt) {
+        const remotePeer = evt.detail.remotePeer;
+        this.logger.debug(`Connection closed to: ${remotePeer.toString()}`);
+    }
+    /**
+     * Try to resolve a libp2p peer ID to an Olane address
+     * Checks hierarchy manager for known peers
+     */
+    peerIdToAddress(peerId) {
+        // Check children
+        for (const child of this.hierarchyManager.children) {
+            const childTransports = child.transports;
+            for (const transport of childTransports) {
+                if (transport.toString().includes(peerId)) {
+                    return child;
+                }
+            }
+        }
+        // Check parents
+        for (const parent of this.hierarchyManager.parents) {
+            const parentTransports = parent.transports;
+            for (const transport of parentTransports) {
+                if (transport.toString().includes(peerId)) {
+                    return parent;
+                }
+            }
+        }
+        // Check leaders
+        for (const leader of this.hierarchyManager.leaders) {
+            const leaderTransports = leader.transports;
+            for (const transport of leaderTransports) {
+                if (transport.toString().includes(peerId)) {
+                    return leader;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if an address is a direct child
+     */
+    isChild(address) {
+        return this.hierarchyManager.children.some((child) => child.toString() === address.toString());
+    }
+    /**
+     * Check if an address is a parent
+     */
+    isParent(address) {
+        return this.hierarchyManager.parents.some((parent) => parent.toString() === address.toString());
+    }
+}

package/dist/src/o-node.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAGR,QAAQ,EAET,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAGrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IACzC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAQhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CAa5D"}
+{"version":3,"file":"o-node.tool.d.ts","sourceRoot":"","sources":["../../src/o-node.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,QAAQ,EAGR,QAAQ,EAGT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;;AAIrD;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,cAAkB;IACzC,cAAc,CAAC,OAAO,EAAE,QAAQ;IAQhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDnE,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAQ9B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;CA2B5D"}

package/dist/src/o-node.tool.js

@@ -1,7 +1,8 @@
-import { CoreUtils, oAddress, oError, oErrorCodes, oRequest, } from '@olane/o-core';
+import { CoreUtils, oError, oErrorCodes, oRequest, ChildJoinedEvent, } from '@olane/o-core';
 import { oTool } from '@olane/o-tool';
 import { oServerNode } from './nodes/server.node.js';
 import { oNodeTransport } from './router/o-node.transport.js';
+import { oNodeAddress } from './router/o-node.address.js';
 /**
  * oTool is a mixin that extends the base class and implements the oTool interface
  * @param Base - The base class to extend
@@ -69,8 +70,17 @@ export class oNodeTool extends oTool(oServerNode) {
     async _tool_child_register(request) {
         this.logger.debug('Child register: ', request.params);
         const { address, transports } = request.params;
-        const childAddress = new oAddress(address, transports.map((t) => new oNodeTransport(t)));
+        const childAddress = new oNodeAddress(address, transports.map((t) => new oNodeTransport(t)));
+        // Add child to hierarchy
         this.hierarchyManager.addChild(childAddress);
+        // Emit child joined event
+        if (this.notificationManager) {
+            this.notificationManager.emit(new ChildJoinedEvent({
+                source: this.address,
+                childAddress,
+                parentAddress: this.address,
+            }));
+        }
         return {
             message: `Child node registered with parent! ${childAddress.toString()}`,
             parentTransports: this.parentTransports.map((t) => t.toString()),

package/dist/src/utils/leader-request-wrapper.d.ts

@@ -0,0 +1,45 @@
+import { oObject, oAddress } from '@olane/o-core';
+export interface LeaderRetryConfig {
+    enabled: boolean;
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    timeoutMs: number;
+}
+/**
+ * Leader Request Wrapper
+ *
+ * Wraps requests to leader/registry with aggressive retry logic.
+ * Used when leader may be temporarily unavailable (healing, maintenance).
+ *
+ * Strategy:
+ * 1. Detect if request is to leader or registry
+ * 2. Apply retry logic with exponential backoff
+ * 3. Timeout individual attempts
+ * 4. Log retries for observability
+ */
+export declare class LeaderRequestWrapper extends oObject {
+    private config;
+    constructor(config: LeaderRetryConfig);
+    /**
+     * Check if address is a leader-related address that needs retry
+     */
+    private isLeaderAddress;
+    /**
+     * Execute request with retry logic
+     */
+    execute<T>(requestFn: () => Promise<T>, address: oAddress, context?: string): Promise<T>;
+    /**
+     * Calculate exponential backoff delay
+     */
+    private calculateBackoffDelay;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+    /**
+     * Get current configuration
+     */
+    getConfig(): LeaderRetryConfig;
+}
+//# sourceMappingURL=leader-request-wrapper.d.ts.map

package/dist/src/utils/leader-request-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leader-request-wrapper.d.ts","sourceRoot":"","sources":["../../../src/utils/leader-request-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAuB,MAAM,eAAe,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,OAAO;IACnC,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAI7C;;OAEG;IACH,OAAO,CAAC,eAAe;IAKvB;;OAEG;IACG,OAAO,CAAC,CAAC,EACb,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,QAAQ,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC;IAoEb;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACH,SAAS,IAAI,iBAAiB;CAG/B"}

package/dist/src/utils/leader-request-wrapper.js

@@ -0,0 +1,89 @@
+import { oObject } from '@olane/o-core';
+/**
+ * Leader Request Wrapper
+ *
+ * Wraps requests to leader/registry with aggressive retry logic.
+ * Used when leader may be temporarily unavailable (healing, maintenance).
+ *
+ * Strategy:
+ * 1. Detect if request is to leader or registry
+ * 2. Apply retry logic with exponential backoff
+ * 3. Timeout individual attempts
+ * 4. Log retries for observability
+ */
+export class LeaderRequestWrapper extends oObject {
+    constructor(config) {
+        super();
+        this.config = config;
+    }
+    /**
+     * Check if address is a leader-related address that needs retry
+     */
+    isLeaderAddress(address) {
+        const addressStr = address.toString();
+        return addressStr === 'o://leader' || addressStr === 'o://registry';
+    }
+    /**
+     * Execute request with retry logic
+     */
+    async execute(requestFn, address, context) {
+        // If retry disabled or not a leader address, execute directly
+        if (!this.config.enabled || !this.isLeaderAddress(address)) {
+            return await requestFn();
+        }
+        let attempt = 0;
+        let lastError;
+        while (attempt < this.config.maxAttempts) {
+            attempt++;
+            try {
+                this.logger.debug(`Leader request attempt ${attempt}/${this.config.maxAttempts}` +
+                    (context ? ` (${context})` : ''));
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error(`Leader request timeout after ${this.config.timeoutMs}ms`)), this.config.timeoutMs);
+                });
+                // Race between request and timeout
+                const result = await Promise.race([requestFn(), timeoutPromise]);
+                // Success!
+                if (attempt > 1) {
+                    this.logger.info(`Leader request succeeded after ${attempt} attempts` +
+                        (context ? ` (${context})` : ''));
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                this.logger.warn(`Leader request attempt ${attempt} failed: ${lastError.message}` +
+                    (context ? ` (${context})` : ''));
+                if (attempt < this.config.maxAttempts) {
+                    const delay = this.calculateBackoffDelay(attempt);
+                    this.logger.debug(`Waiting ${delay}ms before next attempt...`);
+                    await this.sleep(delay);
+                }
+            }
+        }
+        // All attempts failed
+        this.logger.error(`Leader request failed after ${this.config.maxAttempts} attempts` +
+            (context ? ` (${context})` : ''));
+        throw lastError || new Error('Leader request failed');
+    }
+    /**
+     * Calculate exponential backoff delay
+     */
+    calculateBackoffDelay(attempt) {
+        const delay = this.config.baseDelayMs * Math.pow(2, attempt - 1);
+        return Math.min(delay, this.config.maxDelayMs);
+    }
+    /**
+     * Sleep utility
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-node",
-  "version": "0.7.12-alpha.5",
+  "version": "0.7.12-alpha.9",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -54,12 +54,12 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-config": "0.7.12-alpha.5",
-    "@olane/o-core": "0.7.12-alpha.4",
-    "@olane/o-protocol": "0.7.12-alpha.4",
-    "@olane/o-tool": "0.7.12-alpha.5",
+    "@olane/o-config": "0.7.12-alpha.9",
+    "@olane/o-core": "0.7.12-alpha.9",
+    "@olane/o-protocol": "0.7.12-alpha.9",
+    "@olane/o-tool": "0.7.12-alpha.9",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0"
   },
-  "gitHead": "f0b799131f025624da04374b76e9aa373402f787"
+  "gitHead": "21427acbdc1d87ff9465bf19bda58cca89e8d3c7"
 }