@ornexus/neocortex 4.0.1

package/packages/client/dist/resilience/circuit-breaker.js

@@ -0,0 +1,170 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Persistent Circuit Breaker
+ *
+ * Circuit breaker with file-based state persistence for the CLI client.
+ * Tracks server health using window-based failure counting and persists
+ * state between CLI invocations at ~/.neocortex/.circuit-state.
+ *
+ * States:
+ *   CLOSED    - Normal operation, requests pass through
+ *   OPEN      - Circuit tripped, requests fail immediately (use cache)
+ *   HALF_OPEN - Testing if server recovered (one probe request allowed)
+ *
+ * Story 42.9
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// ── Defaults ──────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    failureThreshold: 3,
+    failureWindowMs: 60_000,
+    halfOpenAfterMs: 60_000,
+    stateFilePath: join(homedir(), '.neocortex', '.circuit-state'),
+};
+const INITIAL_STATE = {
+    state: 'CLOSED',
+    failures: [],
+    openedAt: null,
+    lastProbeAt: null,
+};
+// ── ClientCircuitBreaker ──────────────────────────────────────────────────
+export class ClientCircuitBreaker {
+    config;
+    internalState;
+    constructor(config, initialState) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.internalState = initialState ? { ...initialState } : { ...INITIAL_STATE, failures: [] };
+    }
+    /**
+     * Check if a request can be made to the server.
+     * Returns false if circuit is OPEN (fail-fast to cache).
+     */
+    canCall() {
+        this.pruneExpiredFailures();
+        switch (this.internalState.state) {
+            case 'CLOSED':
+                return true;
+            case 'OPEN': {
+                const now = Date.now();
+                const openedAt = this.internalState.openedAt ?? 0;
+                if (now - openedAt >= this.config.halfOpenAfterMs) {
+                    this.internalState.state = 'HALF_OPEN';
+                    this.internalState.lastProbeAt = now;
+                    return true;
+                }
+                return false;
+            }
+            case 'HALF_OPEN':
+                return true;
+            default:
+                return true;
+        }
+    }
+    /**
+     * Record a successful server response. Closes the circuit.
+     */
+    async recordSuccess() {
+        this.internalState.state = 'CLOSED';
+        this.internalState.failures = [];
+        this.internalState.openedAt = null;
+        this.internalState.lastProbeAt = null;
+        await this.saveToDisk();
+    }
+    /**
+     * Record a failed server response. Opens circuit after threshold failures in window.
+     */
+    async recordFailure() {
+        const now = Date.now();
+        this.internalState.failures.push({ timestamp: now });
+        this.pruneExpiredFailures();
+        if (this.internalState.failures.length >= this.config.failureThreshold) {
+            this.internalState.state = 'OPEN';
+            this.internalState.openedAt = now;
+        }
+        // If in HALF_OPEN and probe fails, go back to OPEN
+        if (this.internalState.state === 'HALF_OPEN') {
+            this.internalState.state = 'OPEN';
+            this.internalState.openedAt = now;
+        }
+        await this.saveToDisk();
+    }
+    /**
+     * Get current circuit breaker state (copy).
+     */
+    getState() {
+        this.pruneExpiredFailures();
+        return {
+            state: this.internalState.state,
+            failures: [...this.internalState.failures],
+            openedAt: this.internalState.openedAt,
+            lastProbeAt: this.internalState.lastProbeAt,
+        };
+    }
+    /**
+     * Reset circuit breaker to initial CLOSED state.
+     */
+    async reset() {
+        this.internalState = { ...INITIAL_STATE, failures: [] };
+        await this.saveToDisk();
+    }
+    /**
+     * Load circuit breaker state from disk.
+     */
+    static async loadFromDisk(path) {
+        const filePath = path ?? DEFAULT_CONFIG.stateFilePath;
+        try {
+            const raw = await readFile(filePath, 'utf8');
+            const data = JSON.parse(raw);
+            // Validate loaded state
+            if (!data.state || !Array.isArray(data.failures)) {
+                return new ClientCircuitBreaker({ stateFilePath: filePath });
+            }
+            return new ClientCircuitBreaker({ stateFilePath: filePath }, data);
+        }
+        catch {
+            // File doesn't exist or is corrupted - start fresh
+            return new ClientCircuitBreaker({ stateFilePath: filePath });
+        }
+    }
+    // ── Private ─────────────────────────────────────────────────────────
+    /**
+     * Remove failures outside the counting window.
+     */
+    pruneExpiredFailures() {
+        const cutoff = Date.now() - this.config.failureWindowMs;
+        this.internalState.failures = this.internalState.failures.filter((f) => f.timestamp > cutoff);
+    }
+    /**
+     * Persist state to disk with atomic write.
+     */
+    async saveToDisk() {
+        try {
+            const dir = dirname(this.config.stateFilePath);
+            await mkdir(dir, { recursive: true });
+            const tmpPath = `${this.config.stateFilePath}.tmp`;
+            const data = JSON.stringify(this.internalState, null, 2);
+            await writeFile(tmpPath, data, 'utf8');
+            // Atomic rename
+            const { rename } = await import('node:fs/promises');
+            await rename(tmpPath, this.config.stateFilePath);
+        }
+        catch {
+            // Persistence failures are non-critical - circuit breaker
+            // still works in-memory for current session
+        }
+    }
+}

package/packages/client/dist/resilience/degradation-manager.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Degradation Manager
+ *
+ * Evaluates current degradation level (L0-L4) based on circuit breaker state,
+ * measured latency, cache availability and freshness. Returns a decision
+ * object that tells the resolver how to behave.
+ *
+ * Story 42.9
+ */
+import type { CircuitState } from './circuit-breaker.js';
+export declare enum DegradationLevel {
+    /** Server available, fresh data, optimal performance */
+    ONLINE = 0,
+    /** Server slow (>2s), use cache when available */
+    HIGH_LATENCY = 1,
+    /** Server down, use cache exclusively */
+    SERVER_DOWN = 2,
+    /** Cache expired (>24h), use with warning */
+    STALE_CACHE = 3,
+    /** No cache and no server - error state */
+    NO_CACHE = 4
+}
+export interface DegradationContext {
+    circuitState: CircuitState;
+    latencyMs?: number;
+    cacheAvailable: boolean;
+    cacheAgeMs?: number;
+    forceOffline: boolean;
+}
+export interface DegradationDecision {
+    level: DegradationLevel;
+    useCache: boolean;
+    useServer: boolean;
+    prefix: string;
+    warning: string | null;
+}
+export interface DegradationManagerConfig {
+    /** Cache age threshold for STALE warning. Default: 86_400_000 (24h) */
+    staleThresholdMs: number;
+    /** Cache age threshold for initial warning. Default: 43_200_000 (12h) */
+    warningThresholdMs: number;
+    /** Latency threshold for HIGH_LATENCY level. Default: 2000 (2s) */
+    latencyThresholdMs: number;
+}
+export declare class DegradationManager {
+    private readonly config;
+    constructor(config?: Partial<DegradationManagerConfig>);
+    /**
+     * Evaluate the current degradation level based on context.
+     */
+    evaluate(context: DegradationContext): DegradationDecision;
+    private buildServerDownDecision;
+    private buildCacheOnlyDecision;
+    private formatAge;
+}

package/packages/client/dist/resilience/degradation-manager.js

@@ -0,0 +1,164 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+// ── Types ─────────────────────────────────────────────────────────────────
+export var DegradationLevel;
+(function (DegradationLevel) {
+    /** Server available, fresh data, optimal performance */
+    DegradationLevel[DegradationLevel["ONLINE"] = 0] = "ONLINE";
+    /** Server slow (>2s), use cache when available */
+    DegradationLevel[DegradationLevel["HIGH_LATENCY"] = 1] = "HIGH_LATENCY";
+    /** Server down, use cache exclusively */
+    DegradationLevel[DegradationLevel["SERVER_DOWN"] = 2] = "SERVER_DOWN";
+    /** Cache expired (>24h), use with warning */
+    DegradationLevel[DegradationLevel["STALE_CACHE"] = 3] = "STALE_CACHE";
+    /** No cache and no server - error state */
+    DegradationLevel[DegradationLevel["NO_CACHE"] = 4] = "NO_CACHE";
+})(DegradationLevel || (DegradationLevel = {}));
+// ── Defaults ──────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    staleThresholdMs: 86_400_000, // 24 hours
+    warningThresholdMs: 43_200_000, // 12 hours
+    latencyThresholdMs: 2_000, // 2 seconds
+};
+// ── DegradationManager ───────────────────────────────────────────────────
+export class DegradationManager {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Evaluate the current degradation level based on context.
+     */
+    evaluate(context) {
+        // Force-offline mode: always use cache
+        if (context.forceOffline) {
+            return this.buildCacheOnlyDecision(context, '[OFFLINE]');
+        }
+        // Circuit is OPEN: server known to be down
+        if (context.circuitState === 'OPEN') {
+            return this.buildServerDownDecision(context);
+        }
+        // Circuit is HALF_OPEN: probing server
+        if (context.circuitState === 'HALF_OPEN') {
+            // Allow server request (probe), but prepare cache fallback
+            return {
+                level: DegradationLevel.SERVER_DOWN,
+                useCache: true,
+                useServer: true,
+                prefix: '[PROBING]',
+                warning: null,
+            };
+        }
+        // Circuit is CLOSED: server available
+        if (context.latencyMs != null && context.latencyMs > this.config.latencyThresholdMs) {
+            // High latency: prefer cache if available
+            if (context.cacheAvailable) {
+                return {
+                    level: DegradationLevel.HIGH_LATENCY,
+                    useCache: true,
+                    useServer: false,
+                    prefix: '[CACHED]',
+                    warning: null,
+                };
+            }
+            // No cache available: still use server (slow is better than nothing)
+            return {
+                level: DegradationLevel.HIGH_LATENCY,
+                useCache: false,
+                useServer: true,
+                prefix: '',
+                warning: 'Server response is slow. Consider running `neocortex cache warmup`.',
+            };
+        }
+        // Normal operation
+        return {
+            level: DegradationLevel.ONLINE,
+            useCache: false,
+            useServer: true,
+            prefix: '',
+            warning: null,
+        };
+    }
+    // ── Private ─────────────────────────────────────────────────────────
+    buildServerDownDecision(context) {
+        if (!context.cacheAvailable) {
+            return {
+                level: DegradationLevel.NO_CACHE,
+                useCache: false,
+                useServer: false,
+                prefix: '[ERROR]',
+                warning: 'Server unavailable and no cached data. Run `neocortex cache warmup` when online.',
+            };
+        }
+        const cacheAgeMs = context.cacheAgeMs ?? 0;
+        if (cacheAgeMs > this.config.staleThresholdMs) {
+            const ageStr = this.formatAge(cacheAgeMs);
+            return {
+                level: DegradationLevel.STALE_CACHE,
+                useCache: true,
+                useServer: false,
+                prefix: `[STALE CACHE - ${ageStr}]`,
+                warning: `Cache is stale (${ageStr} old). Data may be outdated.`,
+            };
+        }
+        return {
+            level: DegradationLevel.SERVER_DOWN,
+            useCache: true,
+            useServer: false,
+            prefix: '[CACHED]',
+            warning: cacheAgeMs > this.config.warningThresholdMs
+                ? `Cache is ${this.formatAge(cacheAgeMs)} old.`
+                : null,
+        };
+    }
+    buildCacheOnlyDecision(context, prefix) {
+        if (!context.cacheAvailable) {
+            return {
+                level: DegradationLevel.NO_CACHE,
+                useCache: false,
+                useServer: false,
+                prefix: '[ERROR]',
+                warning: 'Offline mode active but no cached data available. Run `neocortex cache warmup` when online.',
+            };
+        }
+        const cacheAgeMs = context.cacheAgeMs ?? 0;
+        if (cacheAgeMs > this.config.staleThresholdMs) {
+            const ageStr = this.formatAge(cacheAgeMs);
+            return {
+                level: DegradationLevel.STALE_CACHE,
+                useCache: true,
+                useServer: false,
+                prefix: `[STALE CACHE - ${ageStr}]`,
+                warning: `Using stale cache (${ageStr} old) in offline mode.`,
+            };
+        }
+        return {
+            level: DegradationLevel.SERVER_DOWN,
+            useCache: true,
+            useServer: false,
+            prefix,
+            warning: null,
+        };
+    }
+    formatAge(ms) {
+        const hours = Math.floor(ms / 3_600_000);
+        if (hours >= 48)
+            return `${Math.floor(hours / 24)}d`;
+        if (hours >= 1)
+            return `${hours}h`;
+        const minutes = Math.floor(ms / 60_000);
+        if (minutes >= 1)
+            return `${minutes}m`;
+        return '<1m';
+    }
+}

package/packages/client/dist/resilience/freshness-indicator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Freshness Indicator
+ *
+ * Enriches cache responses with freshness metadata for user-facing display.
+ * Formats cache age as human-readable strings and generates appropriate
+ * warning prefixes based on degradation level.
+ *
+ * Story 42.9
+ */
+import { DegradationLevel } from './degradation-manager.js';
+export interface FreshnessInfo {
+    /** Whether the response came from cache */
+    cached: boolean;
+    /** Age of cached entry in milliseconds */
+    cacheAgeMs: number;
+    /** Whether the cache entry is considered stale (>24h) */
+    stale: boolean;
+    /** Warning message if applicable, null otherwise */
+    warning: string | null;
+    /** Display prefix for CLI output */
+    prefix: string;
+    /** Version of the cached asset (if known) */
+    version?: string;
+}
+export interface FreshnessConfig {
+    /** Threshold in ms for stale warning. Default: 86_400_000 (24h) */
+    staleThresholdMs: number;
+    /** Threshold in ms for age warning. Default: 43_200_000 (12h) */
+    warningThresholdMs: number;
+}
+export declare class FreshnessIndicator {
+    private readonly config;
+    constructor(config?: Partial<FreshnessConfig>);
+    /**
+     * Format a duration in ms as human-readable age string.
+     * Examples: "30m ago", "4h ago", "2d ago"
+     */
+    formatAge(ageMs: number): string;
+    /**
+     * Evaluate freshness of a cache entry.
+     */
+    evaluate(cacheAgeMs: number, _ttlMs?: number): FreshnessInfo;
+    /**
+     * Format prefix string based on degradation level and optional age.
+     */
+    formatPrefix(level: DegradationLevel, ageMs?: number): string;
+}

package/packages/client/dist/resilience/freshness-indicator.js

@@ -0,0 +1,100 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Freshness Indicator
+ *
+ * Enriches cache responses with freshness metadata for user-facing display.
+ * Formats cache age as human-readable strings and generates appropriate
+ * warning prefixes based on degradation level.
+ *
+ * Story 42.9
+ */
+import { DegradationLevel } from './degradation-manager.js';
+// ── Defaults ──────────────────────────────────────────────────────────────
+const DEFAULT_CONFIG = {
+    staleThresholdMs: 86_400_000, // 24 hours
+    warningThresholdMs: 43_200_000, // 12 hours
+};
+// ── FreshnessIndicator ──────────────────────────────────────────────────
+export class FreshnessIndicator {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Format a duration in ms as human-readable age string.
+     * Examples: "30m ago", "4h ago", "2d ago"
+     */
+    formatAge(ageMs) {
+        if (ageMs < 0)
+            return 'just now';
+        const seconds = Math.floor(ageMs / 1_000);
+        const minutes = Math.floor(ageMs / 60_000);
+        const hours = Math.floor(ageMs / 3_600_000);
+        const days = Math.floor(ageMs / 86_400_000);
+        if (days >= 1)
+            return `${days}d ago`;
+        if (hours >= 1)
+            return `${hours}h ago`;
+        if (minutes >= 1)
+            return `${minutes}m ago`;
+        if (seconds >= 1)
+            return `${seconds}s ago`;
+        return 'just now';
+    }
+    /**
+     * Evaluate freshness of a cache entry.
+     */
+    evaluate(cacheAgeMs, _ttlMs) {
+        const stale = cacheAgeMs > this.config.staleThresholdMs;
+        const aged = cacheAgeMs > this.config.warningThresholdMs;
+        let warning = null;
+        let prefix = '[CACHED]';
+        if (stale) {
+            const ageStr = this.formatAge(cacheAgeMs);
+            prefix = `[STALE CACHE - ${ageStr}]`;
+            warning = `WARNING: STALE - cached ${ageStr}`;
+        }
+        else if (aged) {
+            const ageStr = this.formatAge(cacheAgeMs);
+            prefix = `[CACHED]`;
+            warning = `WARNING - cached ${ageStr}`;
+        }
+        return {
+            cached: true,
+            cacheAgeMs,
+            stale,
+            warning,
+            prefix,
+        };
+    }
+    /**
+     * Format prefix string based on degradation level and optional age.
+     */
+    formatPrefix(level, ageMs) {
+        switch (level) {
+            case DegradationLevel.ONLINE:
+                return '';
+            case DegradationLevel.HIGH_LATENCY:
+                return ageMs != null ? `[CACHED] cached ${this.formatAge(ageMs)}` : '[CACHED]';
+            case DegradationLevel.SERVER_DOWN:
+                return ageMs != null ? `[CACHED] cached ${this.formatAge(ageMs)}` : '[CACHED]';
+            case DegradationLevel.STALE_CACHE:
+                return ageMs != null ? `[STALE CACHE - ${this.formatAge(ageMs)}]` : '[STALE CACHE]';
+            case DegradationLevel.NO_CACHE:
+                return '[ERROR]';
+            default:
+                return '';
+        }
+    }
+}

package/packages/client/dist/resilience/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { ClientCircuitBreaker, type CircuitState, type CircuitBreakerConfig, type CircuitBreakerState, type FailureRecord } from './circuit-breaker.js';
+export { DegradationManager, DegradationLevel, type DegradationContext, type DegradationDecision, type DegradationManagerConfig } from './degradation-manager.js';
+export { FreshnessIndicator, type FreshnessInfo, type FreshnessConfig } from './freshness-indicator.js';
+export { RecoveryDetector, type RecoveryActions, type RecoveryResult } from './recovery-detector.js';

package/packages/client/dist/resilience/index.js

@@ -0,0 +1,8 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ */
+export { ClientCircuitBreaker } from './circuit-breaker.js';
+export { DegradationManager, DegradationLevel } from './degradation-manager.js';
+export { FreshnessIndicator } from './freshness-indicator.js';
+export { RecoveryDetector } from './recovery-detector.js';

package/packages/client/dist/resilience/recovery-detector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - Recovery Detector
+ *
+ * Coordinates recovery actions when server comes back online after
+ * a circuit breaker trip. Each step is independent - failures in one
+ * don't block the others.
+ *
+ * Recovery sequence:
+ * 1. Close circuit breaker (persist to file)
+ * 2. Re-validate JWT token
+ * 3. Sync cache with fresh server data (background)
+ * 4. Flush offline telemetry queue (background)
+ * 5. Notify user with [ONLINE] prefix
+ *
+ * Story 42.9
+ */
+import type { ClientCircuitBreaker } from './circuit-breaker.js';
+import type { CacheProvider } from '../types/index.js';
+import type { OfflineTelemetryQueue } from '../telemetry/offline-queue.js';
+export interface RecoveryActions {
+    circuitBreaker: ClientCircuitBreaker;
+    licenseClient: {
+        getToken(): Promise<string | null>;
+    };
+    cache: CacheProvider;
+    telemetryQueue: OfflineTelemetryQueue;
+    serverUrl: string;
+}
+export interface RecoveryResult {
+    circuitClosed: boolean;
+    jwtRefreshed: boolean;
+    cacheSynced: boolean;
+    telemetryFlushed: {
+        sent: number;
+        failed: number;
+    };
+    notification: string;
+}
+export declare class RecoveryDetector {
+    private readonly actions;
+    constructor(actions: RecoveryActions);
+    /**
+     * Execute full recovery sequence.
+     * Each step is independent - failures are captured but don't block others.
+     */
+    onRecovery(): Promise<RecoveryResult>;
+}