@pellux/goodvibes-sdk 0.18.14 → 0.18.15

package/dist/_internal/platform/runtime/foundation-services.js

@@ -0,0 +1,40 @@
+import { createUiRuntimeEvents } from './ui-events.js';
+import { createCoreReadModels } from './ui-read-models-core.js';
+import { createOperationsReadModels, } from './ui-read-models-operations.js';
+function createOperatorClientReadModels(runtimeServices, options = {}) {
+    const core = createCoreReadModels(runtimeServices);
+    const operations = createOperationsReadModels(runtimeServices, options);
+    return {
+        controlPlane: operations.controlPlane,
+        providers: core.providers,
+        session: core.session,
+        tasks: core.tasks,
+    };
+}
+export function createOperatorClientServices(runtimeServices, options = {}) {
+    return {
+        events: createUiRuntimeEvents(runtimeServices.runtimeBus),
+        shellPaths: runtimeServices.shellPaths,
+        readModels: createOperatorClientReadModels(runtimeServices, options),
+        sessionBroker: runtimeServices.sessionBroker,
+        approvalBroker: runtimeServices.approvalBroker,
+        providerRegistry: runtimeServices.providerRegistry,
+        serviceRegistry: runtimeServices.serviceRegistry,
+        subscriptionManager: runtimeServices.subscriptionManager,
+        secretsManager: runtimeServices.secretsManager,
+    };
+}
+export function createPeerClientDependencies(runtimeServices) {
+    return {
+        runtimeStore: runtimeServices.runtimeStore,
+        distributedRuntime: runtimeServices.distributedRuntime,
+        remoteRunnerRegistry: runtimeServices.remoteRunnerRegistry,
+        remoteSupervisor: runtimeServices.remoteSupervisor,
+    };
+}
+export function createDirectTransportServices(runtimeServices, options = {}) {
+    return {
+        operator: createOperatorClientServices(runtimeServices, options),
+        peer: createPeerClientDependencies(runtimeServices),
+    };
+}

package/dist/_internal/platform/runtime/guidance.d.ts

@@ -0,0 +1,30 @@
+import type { ConfigManager } from '../config/manager.js';
+import type { SessionMaintenanceStatus } from './session-maintenance.js';
+import type { EcosystemRecommendation } from './ecosystem/recommendations.js';
+export type GuidanceMode = 'off' | 'minimal' | 'guided';
+export type GuidanceCategory = 'onboarding' | 'operational' | 'recovery' | 'optimization';
+export interface GuidanceItem {
+    readonly id: string;
+    readonly category: GuidanceCategory;
+    readonly title: string;
+    readonly summary: string;
+    readonly commands: readonly string[];
+}
+export interface ContextualGuidanceSnapshot {
+    readonly pendingApproval: boolean;
+    readonly denialCount: number;
+    readonly authRequiredMcpCount: number;
+    readonly degradedProviderCount: number;
+    readonly intelligenceUnavailable: boolean;
+    readonly recommendations: readonly EcosystemRecommendation[];
+}
+export interface GuidancePersistenceOptions {
+    readonly guidancePath?: string;
+    readonly userRoot?: string;
+    readonly homeDirectory?: string;
+}
+export declare function dismissGuidance(id: string, options?: GuidancePersistenceOptions): void;
+export declare function resetGuidance(id?: string, options?: GuidancePersistenceOptions): void;
+export declare function evaluateContextualGuidance(configManager: ConfigManager, snapshot: ContextualGuidanceSnapshot, maintenance: SessionMaintenanceStatus, options?: GuidancePersistenceOptions): GuidanceItem[];
+export declare function formatGuidanceItems(items: readonly GuidanceItem[]): string[];
+//# sourceMappingURL=guidance.d.ts.map

package/dist/_internal/platform/runtime/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../../../../src/_internal/platform/runtime/guidance.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;AACxD,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,aAAa,GAAG,UAAU,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC9D;AAOD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AA6BD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAItF;AAED,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAQrF;AAED,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,0BAA0B,EACpC,WAAW,EAAE,wBAAwB,EACrC,OAAO,CAAC,EAAE,0BAA0B,GACnC,YAAY,EAAE,CAuFhB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,EAAE,CAQ5E"}

package/dist/_internal/platform/runtime/guidance.js

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+function resolveGuidancePath(options) {
+    if (options?.guidancePath) {
+        return options.guidancePath;
+    }
+    const userRoot = options?.userRoot ?? options?.homeDirectory;
+    if (!userRoot) {
+        throw new Error('Guidance persistence requires guidancePath or an explicit userRoot/homeDirectory.');
+    }
+    return join(userRoot, '.goodvibes', 'goodvibes', 'guidance.json');
+}
+function readDismissals(options) {
+    try {
+        const guidanceFile = resolveGuidancePath(options);
+        if (!existsSync(guidanceFile))
+            return { version: 1, dismissed: {} };
+        return JSON.parse(readFileSync(guidanceFile, 'utf-8'));
+    }
+    catch {
+        return { version: 1, dismissed: {} };
+    }
+}
+function writeDismissals(store, options) {
+    const guidanceFile = resolveGuidancePath(options);
+    mkdirSync(dirname(guidanceFile), { recursive: true });
+    writeFileSync(guidanceFile, `${JSON.stringify(store, null, 2)}\n`, 'utf-8');
+}
+export function dismissGuidance(id, options) {
+    const store = readDismissals(options);
+    store.dismissed[id] = Date.now();
+    writeDismissals(store, options);
+}
+export function resetGuidance(id, options) {
+    if (!id) {
+        writeDismissals({ version: 1, dismissed: {} }, options);
+        return;
+    }
+    const store = readDismissals(options);
+    delete store.dismissed[id];
+    writeDismissals(store, options);
+}
+export function evaluateContextualGuidance(configManager, snapshot, maintenance, options) {
+    const mode = configManager.get('behavior.guidanceMode') ?? 'minimal';
+    if (mode === 'off')
+        return [];
+    const dismissed = readDismissals(options).dismissed;
+    const items = [];
+    if (maintenance.level === 'suggest-compact' || maintenance.level === 'needs-repair') {
+        items.push({
+            id: 'context-maintenance',
+            category: 'recovery',
+            title: 'Context pressure needs attention',
+            summary: 'The active session is near or beyond its healthy context budget.',
+            commands: maintenance.nextSteps,
+        });
+    }
+    else if (mode === 'guided' && maintenance.level === 'watch') {
+        items.push({
+            id: 'context-watch',
+            category: 'optimization',
+            title: 'Context pressure is rising',
+            summary: 'Context is still healthy, but it is moving toward the configured compaction threshold.',
+            commands: maintenance.nextSteps,
+        });
+    }
+    if (snapshot.pendingApproval) {
+        items.push({
+            id: 'pending-approval',
+            category: 'recovery',
+            title: 'A permission decision is waiting',
+            summary: 'Operator approval is currently blocking the active workflow.',
+            commands: ['/approval', '/security'],
+        });
+    }
+    if (snapshot.denialCount >= 3 && mode === 'guided') {
+        items.push({
+            id: 'repeated-denials',
+            category: 'operational',
+            title: 'Repeated denials suggest a policy mismatch',
+            summary: 'Several actions were denied in this session. Review whether a scoped durable rule should be added.',
+            commands: ['/policy', '/security', '/approval'],
+        });
+    }
+    if (snapshot.authRequiredMcpCount > 0) {
+        items.push({
+            id: 'mcp-auth-required',
+            category: 'recovery',
+            title: 'One or more MCP servers require authentication',
+            summary: `${snapshot.authRequiredMcpCount} MCP server${snapshot.authRequiredMcpCount === 1 ? '' : 's'} cannot operate until auth is completed.`,
+            commands: ['/mcp', '/services auth-review'],
+        });
+    }
+    if (snapshot.degradedProviderCount > 0) {
+        items.push({
+            id: 'provider-health',
+            category: 'recovery',
+            title: 'Provider health is degraded',
+            summary: 'At least one configured provider is rate-limited, unavailable, or in an auth error state.',
+            commands: ['/provider', '/health'],
+        });
+    }
+    if (mode === 'guided' && snapshot.intelligenceUnavailable) {
+        items.push({
+            id: 'intelligence-setup',
+            category: 'onboarding',
+            title: 'Workspace intelligence is not ready',
+            summary: 'Diagnostics and symbol search are unavailable for this workspace. Enable or configure intelligence to improve code-aware workflows.',
+            commands: ['/setup onboarding', '/health'],
+        });
+    }
+    if (snapshot.recommendations.length > 0) {
+        const top = snapshot.recommendations[0];
+        items.push({
+            id: 'ecosystem-recommendation',
+            category: 'operational',
+            title: top.title,
+            summary: top.reason,
+            commands: [top.command, '/marketplace recommend'],
+        });
+    }
+    return items.filter((item) => !(item.id in dismissed));
+}
+export function formatGuidanceItems(items) {
+    if (items.length === 0)
+        return ['No active guidance items.'];
+    return items.flatMap((item) => [
+        `[${item.category}] ${item.title}`,
+        `  ${item.summary}`,
+        ...(item.commands.length > 0 ? [`  next: ${item.commands.join('  ')}`] : []),
+        `  dismiss: /guidance dismiss ${item.id}`,
+    ]);
+}

package/dist/_internal/platform/runtime/health/effect-handlers.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Health Error Propagation — Effect Handlers
+ *
+ * Implements concrete actions for each CascadeEffect type produced by the
+ * CascadeEngine. Each handler is a pure dispatch function — side effects
+ * are performed through the provided aggregator and eventBus context.
+ *
+ * Callers (e.g. HealthStoreWiring) are responsible for iterating over
+ * CascadeResult arrays and invoking this function for each result.
+ *
+ * @module health/effect-handlers
+ */
+import type { CascadeEffect, CascadeResult } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+import type { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+import type { RuntimeEventBus } from '../events/index.js';
+/** Context injected into each effect handler. */
+export interface EffectHandlerContext {
+    /** The health aggregator — used to mark domain state changes. */
+    readonly aggregator: RuntimeHealthAggregator;
+    /** The event bus — used to emit CASCADE_APPLIED and domain events. */
+    readonly eventBus: RuntimeEventBus;
+}
+/**
+ * Dispatches the appropriate runtime action for a given CascadeEffect.
+ *
+ * Handles all six CascadeEffect variants:
+ * - `CANCEL_INFLIGHT` — cancels in-flight operations in the given scope
+ * - `BLOCK_DISPATCH` — blocks new dispatch in the given scope (optionally queues)
+ * - `MARK_CHILDREN` — marks child tasks/agents as failed or blocked
+ * - `DEREGISTER_TOOLS` — deregisters tools, scoped by pluginId from sourceContext
+ * - `EMIT_EVENT` — emits a domain event of the given eventType on the bus
+ * - `BLOCK_NEW` — blocks new operations of the given scope
+ *
+ * After applying the effect, emits a `CASCADE_APPLIED` event on the event bus
+ * so that other subsystems can observe cascade propagation.
+ *
+ * @param effect - The CascadeEffect to apply.
+ * @param result - The CascadeResult that produced this effect (carries ruleId, source, etc.).
+ * @param context - The aggregator and eventBus needed to perform side effects.
+ */
+export declare function handleCascadeEffect(effect: CascadeEffect, result: CascadeResult, context: EffectHandlerContext): void;
+//# sourceMappingURL=effect-handlers.d.ts.map

package/dist/_internal/platform/runtime/health/effect-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-handlers.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/effect-handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAC;AAExG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AACxG,OAAO,KAAK,EAAE,eAAe,EAAwB,MAAM,oBAAoB,CAAC;AA6BhF,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAiHN"}

package/dist/_internal/platform/runtime/health/effect-handlers.js

@@ -0,0 +1,148 @@
+/**
+ * Health Error Propagation — Effect Handlers
+ *
+ * Implements concrete actions for each CascadeEffect type produced by the
+ * CascadeEngine. Each handler is a pure dispatch function — side effects
+ * are performed through the provided aggregator and eventBus context.
+ *
+ * Callers (e.g. HealthStoreWiring) are responsible for iterating over
+ * CascadeResult arrays and invoking this function for each result.
+ *
+ * @module health/effect-handlers
+ */
+import { createCascadeAppliedEvent } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+import { createEventEnvelope } from '../events/index.js';
+/**
+ * Emits a synthetic health event on the bus.
+ *
+ * Health events (e.g. CASCADE_APPLIED) are not part of AnyRuntimeEvent — they live
+ * outside the typed domain-event union. This helper centralises the necessary
+ * cross-domain cast in a single, documented location rather than duplicating it
+ * at each call site.
+ */
+/**
+ * GC-ARCH-002 allowlist: This file is explicitly permitted to call
+ * RuntimeEventBus.emit() directly because it emits synthetic health events
+ * (CASCADE_APPLIED, EMIT_EVENT effects) that are intentionally outside the
+ * AnyRuntimeEvent typed union. The necessary cast is isolated here to avoid
+ * duplicating it at every effect-handler call site.
+ *
+ * Do NOT copy this pattern elsewhere — use typed emitters from
+ * src/runtime/emitters/ for all standard domain events.
+ */
+function emitHealthEvent(bus, envelope) {
+    bus.emit('session', envelope);
+}
+/**
+ * Dispatches the appropriate runtime action for a given CascadeEffect.
+ *
+ * Handles all six CascadeEffect variants:
+ * - `CANCEL_INFLIGHT` — cancels in-flight operations in the given scope
+ * - `BLOCK_DISPATCH` — blocks new dispatch in the given scope (optionally queues)
+ * - `MARK_CHILDREN` — marks child tasks/agents as failed or blocked
+ * - `DEREGISTER_TOOLS` — deregisters tools, scoped by pluginId from sourceContext
+ * - `EMIT_EVENT` — emits a domain event of the given eventType on the bus
+ * - `BLOCK_NEW` — blocks new operations of the given scope
+ *
+ * After applying the effect, emits a `CASCADE_APPLIED` event on the event bus
+ * so that other subsystems can observe cascade propagation.
+ *
+ * @param effect - The CascadeEffect to apply.
+ * @param result - The CascadeResult that produced this effect (carries ruleId, source, etc.).
+ * @param context - The aggregator and eventBus needed to perform side effects.
+ */
+export function handleCascadeEffect(effect, result, context) {
+    const { aggregator, eventBus } = context;
+    switch (effect.type) {
+        case 'CANCEL_INFLIGHT': {
+            // Mark the target domain as degraded to signal in-flight cancellation.
+            // Actual cancellation of network/async operations is domain-specific;
+            // subscribers observing CASCADE_APPLIED will perform the real cancellation.
+            if (result.target !== 'ALL') {
+                aggregator.updateDomainHealth(result.target, 'degraded', {
+                    failureReason: `In-flight operations cancelled (scope: ${effect.scope})`,
+                });
+            }
+            break;
+        }
+        case 'BLOCK_DISPATCH': {
+            // Mark the target domain as degraded with the blocked scope noted.
+            // If queueable, subscribers may hold and retry; otherwise, they must reject.
+            if (result.target !== 'ALL') {
+                aggregator.updateDomainHealth(result.target, 'degraded', {
+                    failureReason: effect.queueable
+                        ? `Dispatch blocked (scope: ${effect.scope}) — queuing enabled`
+                        : `Dispatch blocked (scope: ${effect.scope}) — queuing disabled`,
+                    degradedCapabilities: [effect.scope],
+                });
+            }
+            break;
+        }
+        case 'MARK_CHILDREN': {
+            // Mark child domains as failed or blocked.
+            // For 'ALL' target, propagate to tasks and agents as the primary child domains.
+            const childDomains = result.target === 'ALL'
+                ? ['tasks', 'agents']
+                : [result.target];
+            for (const childDomain of childDomains) {
+                aggregator.updateDomainHealth(childDomain, 'failed', {
+                    failureReason: `Marked ${effect.status} by cascade from '${result.source}'${effect.notifyParent ? ' (parent notified)' : ''}`,
+                });
+            }
+            break;
+        }
+        case 'DEREGISTER_TOOLS': {
+            // Signal tool deregistration by marking the toolExecution domain degraded.
+            // Subscribers (tool registry) observe CASCADE_APPLIED to perform actual deregistration.
+            // If pluginId is in sourceContext, the scope is limited to that plugin's tools.
+            const pluginId = result.sourceContext?.['pluginId'];
+            const scope = pluginId ? `plugin:${pluginId}` : 'all-plugins';
+            if (result.target !== 'ALL') {
+                aggregator.updateDomainHealth(result.target, 'degraded', {
+                    failureReason: `Tools deregistered (${scope})`,
+                    degradedCapabilities: [`tool-dispatch:${scope}`],
+                });
+            }
+            break;
+        }
+        case 'EMIT_EVENT': {
+            // Emit the specified event type on the bus as a synthetic health event.
+            // Since CASCADE_APPLIED is not in AnyRuntimeEvent, we use a cast to
+            // emit on the 'session' domain (the most general available routing domain).
+            const syntheticEnvelope = createEventEnvelope(effect.eventType, {
+                type: effect.eventType,
+                ruleId: result.ruleId,
+                source: result.source,
+                target: result.target,
+                timestamp: result.timestamp,
+                sourceContext: result.sourceContext,
+            }, {
+                sessionId: result.sourceContext?.['sessionId'] ?? 'runtime',
+                source: 'health/effect-handlers',
+            });
+            emitHealthEvent(eventBus, syntheticEnvelope);
+            break;
+        }
+        case 'BLOCK_NEW': {
+            // Block new operations in the given scope by marking target domain degraded.
+            if (result.target !== 'ALL') {
+                aggregator.updateDomainHealth(result.target, 'degraded', {
+                    failureReason: `New operations blocked (scope: ${effect.scope})`,
+                    degradedCapabilities: [effect.scope],
+                });
+            }
+            break;
+        }
+        default: {
+            const _exhaustive = effect;
+            throw new Error(`Unhandled cascade effect type: ${effect.type}`);
+        }
+    }
+    // Emit CASCADE_APPLIED event for observability
+    const appliedEvent = createCascadeAppliedEvent(result);
+    const appliedEnvelope = createEventEnvelope('CASCADE_APPLIED', appliedEvent, {
+        sessionId: result.sourceContext?.['sessionId'] ?? 'runtime',
+        source: 'health/effect-handlers',
+    });
+    emitHealthEvent(eventBus, appliedEnvelope);
+}

package/dist/_internal/platform/runtime/health/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Runtime health monitoring system — barrel exports and factory.
+ *
+ * Usage:
+ * ```ts
+ * import { createHealthSystem } from './health/index.js';
+ * const { aggregator, cascadeEngine } = createHealthSystem();
+ * ```
+ */
+export type { HealthStatus, HealthDomain, DomainHealth, CompositeHealth, CascadeEffect, CascadeRule, CascadeResult, EvaluateResult, CascadeAppliedEvent, } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+export { createCascadeAppliedEvent } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+export { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+export { CascadeEngine } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-engine';
+export { CASCADE_RULES } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-rules';
+export { HealthStoreWiring } from './wiring.js';
+export { handleCascadeEffect } from './effect-handlers.js';
+export type { EffectHandlerContext } from './effect-handlers.js';
+export { CascadeTimer, deriveCascadeSeverity } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-timing';
+export type { CascadeSeverity, TimedCascadeResult, TimedEvaluateResult } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-timing';
+export { CASCADE_PLAYBOOK_MAP, ALL_CASCADE_RULE_IDS } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-playbook-map';
+import { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+import { CascadeEngine } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-engine';
+import { HealthStoreWiring } from './wiring.js';
+/**
+ * Factory function that creates a fully wired health monitoring system.
+ * The CascadeEngine is pre-loaded with all cascade rules from the rules table.
+ *
+ * @returns aggregator for tracking domain health, and cascadeEngine for evaluating cascades.
+ */
+export declare function createHealthSystem(): {
+    aggregator: RuntimeHealthAggregator;
+    cascadeEngine: CascadeEngine;
+};
+/**
+ * Factory function that creates a fully wired health monitoring system
+ * with error propagation connected to the event bus.
+ *
+ * @param eventBus - The RuntimeEventBus to receive CASCADE_APPLIED events.
+ * @returns aggregator, cascadeEngine, and the wiring controller.
+ */
+export declare function createWiredHealthSystem(eventBus: import('../events/index.js').RuntimeEventBus): {
+    aggregator: RuntimeHealthAggregator;
+    cascadeEngine: CascadeEngine;
+    wiring: HealthStoreWiring;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/_internal/platform/runtime/health/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,aAAa,EACb,WAAW,EACX,aAAa,EACb,cAAc,EACd,mBAAmB,GACpB,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,yBAAyB,EAAE,MAAM,qDAAqD,CAAC;AAEhG,OAAO,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,6DAA6D,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,8DAA8D,CAAC;AACnH,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,8DAA8D,CAAC;AAC7I,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oEAAoE,CAAC;AAEhI,OAAO,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AACnG,OAAO,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAE7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI;IACpC,UAAU,EAAE,uBAAuB,CAAC;IACpC,aAAa,EAAE,aAAa,CAAC;CAC9B,CAIA;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,oBAAoB,EAAE,eAAe,GAAG;IAC/F,UAAU,EAAE,uBAAuB,CAAC;IACpC,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAKA"}

package/dist/_internal/platform/runtime/health/index.js

@@ -0,0 +1,45 @@
+/**
+ * Runtime health monitoring system — barrel exports and factory.
+ *
+ * Usage:
+ * ```ts
+ * import { createHealthSystem } from './health/index.js';
+ * const { aggregator, cascadeEngine } = createHealthSystem();
+ * ```
+ */
+export { createCascadeAppliedEvent } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+export { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+export { CascadeEngine } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-engine';
+export { CASCADE_RULES } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-rules';
+export { HealthStoreWiring } from './wiring.js';
+export { handleCascadeEffect } from './effect-handlers.js';
+export { CascadeTimer, deriveCascadeSeverity } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-timing';
+export { CASCADE_PLAYBOOK_MAP, ALL_CASCADE_RULE_IDS } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-playbook-map';
+import { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+import { CascadeEngine } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-engine';
+import { CASCADE_RULES } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-rules';
+import { HealthStoreWiring } from './wiring.js';
+/**
+ * Factory function that creates a fully wired health monitoring system.
+ * The CascadeEngine is pre-loaded with all cascade rules from the rules table.
+ *
+ * @returns aggregator for tracking domain health, and cascadeEngine for evaluating cascades.
+ */
+export function createHealthSystem() {
+    const aggregator = new RuntimeHealthAggregator();
+    const cascadeEngine = new CascadeEngine(CASCADE_RULES, aggregator);
+    return { aggregator, cascadeEngine };
+}
+/**
+ * Factory function that creates a fully wired health monitoring system
+ * with error propagation connected to the event bus.
+ *
+ * @param eventBus - The RuntimeEventBus to receive CASCADE_APPLIED events.
+ * @returns aggregator, cascadeEngine, and the wiring controller.
+ */
+export function createWiredHealthSystem(eventBus) {
+    const aggregator = new RuntimeHealthAggregator();
+    const cascadeEngine = new CascadeEngine(CASCADE_RULES, aggregator);
+    const wiring = new HealthStoreWiring(aggregator, cascadeEngine, eventBus);
+    return { aggregator, cascadeEngine, wiring };
+}

package/dist/_internal/platform/runtime/health/wiring.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Health Error Propagation — HealthStoreWiring
+ *
+ * Wires together the RuntimeHealthAggregator, CascadeEngine, and RuntimeEventBus
+ * to form a complete error-propagation pipeline. When a domain health status
+ * changes, the wiring evaluates cascade rules and applies their effects.
+ *
+ * Lifecycle:
+ * 1. Call `start()` to subscribe to aggregator health changes.
+ * 2. Call `evaluateDomain()` to push a domain health update and trigger cascades.
+ * 3. Call `stop()` to unsubscribe and release all listeners.
+ *
+ * @module health/wiring
+ */
+import type { HealthDomain, HealthStatus } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+import type { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+import type { CascadeEngine } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-engine';
+import type { RuntimeEventBus } from '../events/index.js';
+/**
+ * Wires the health aggregator, cascade engine, and event bus together.
+ *
+ * Orchestrates the full error-propagation pipeline:
+ * domain health change → cascade evaluation → effect application → event emission.
+ */
+export declare class HealthStoreWiring {
+    private readonly aggregator;
+    private readonly cascadeEngine;
+    private readonly eventBus;
+    private unsubscribe;
+    /**
+     * @param aggregator - Tracks per-domain health; source of health change events.
+     * @param cascadeEngine - Evaluates declarative cascade rules against domain health.
+     * @param eventBus - Receives CASCADE_APPLIED and synthetic domain events.
+     */
+    constructor(aggregator: RuntimeHealthAggregator, cascadeEngine: CascadeEngine, eventBus: RuntimeEventBus);
+    /**
+     * Start listening to aggregator health changes.
+     *
+     * When any domain health changes (detected via aggregator subscribers),
+     * the cascade engine is not automatically re-evaluated for subscriber-driven
+     * changes — callers should use `evaluateDomain()` for explicit cascade evaluation.
+     *
+     * Calling `start()` on an already-started wiring replaces the existing
+     * subscription without leaking the old one.
+     */
+    start(): void;
+    /**
+     * Stop listening to aggregator health changes and release all resources.
+     *
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    stop(): void;
+    /**
+     * Update a domain's health status and evaluate cascade rules.
+     *
+     * Pipeline:
+     * 1. Update the domain health in the aggregator.
+     * 2. Evaluate cascade rules for the new domain + status.
+     * 3. Apply all actionable cascade effects via effect handlers.
+     *    Pending-recovery effects are NOT applied — they await recovery exhaustion.
+     *
+     * @param domain - The domain whose health has changed.
+     * @param status - The new health status for the domain.
+     * @param sourceContext - Optional context identifying the triggering entity
+     *   (e.g. `{ pluginId: 'my-plugin' }`). Propagated into CascadeResult.
+     */
+    evaluateDomain(domain: HealthDomain, status: HealthStatus, sourceContext?: Record<string, string>): void;
+}
+//# sourceMappingURL=wiring.d.ts.map

package/dist/_internal/platform/runtime/health/wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiring.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/health/wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AACtG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AACxG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D;;;;;GAKG;AACH,qBAAa,iBAAiB;IAS1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAV3B,OAAO,CAAC,WAAW,CAA6B;IAEhD;;;;OAIG;gBAEgB,UAAU,EAAE,uBAAuB,EACnC,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,eAAe;IAG5C;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI;IAoBb;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAKZ;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,YAAY,EACpB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,IAAI;CAeR"}