@pellux/goodvibes-tui 0.18.4

package/src/runtime/forensics/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Forensics subsystem — public API.
+ *
+ * Usage:
+ * 1. Create a ForensicsRegistry owned by the current runtime/session.
+ * 2. Create a ForensicsCollector, passing the RuntimeEventBus and registry.
+ * 3. The collector auto-generates reports on terminal failure states.
+ * 4. Pass the registry to ForensicsPanel (diagnostic provider) and the
+ *    /forensics command handler via CommandContext.forensicsRegistry.
+ */
+export type {
+  FailureReport,
+  FailureClass,
+  PhaseTimingEntry,
+  CausalChainEntry,
+  ForensicsJumpLink,
+  ForensicsBundle,
+  ForensicsReplayEvidence,
+  ForensicsEvidenceSummary,
+} from '@pellux/goodvibes-sdk/platform/runtime/forensics/types';
+export { classifyFailure, summariseFailure } from '@pellux/goodvibes-sdk/platform/runtime/forensics/classifier';
+export { ForensicsRegistry, DEFAULT_REGISTRY_LIMIT } from '@pellux/goodvibes-sdk/platform/runtime/forensics/registry';
+export { ForensicsCollector } from './collector.ts';

package/src/runtime/foundation-clients.ts

@@ -0,0 +1,78 @@
+import { listHookPointContracts } from '../hooks/index.ts';
+import type { HookApi } from '../hooks/hook-api.ts';
+import type { KnowledgeApi } from '../knowledge/knowledge-api.ts';
+import type { McpApi } from '../mcp/mcp-api.ts';
+import type { ProviderApi } from '../providers/provider-api.ts';
+import type { RuntimeServices } from './services.ts';
+import {
+  createDirectTransportServices,
+  type DirectTransportServices,
+  type OperatorClientServicesOptions,
+} from './foundation-services.ts';
+import type { OpsApi } from './ops-api.ts';
+import type { OpsControlPlane } from './ops/control-plane.ts';
+import { createRuntimeHookApi } from './runtime-hook-api.ts';
+import { createRuntimeKnowledgeApi } from './runtime-knowledge-api.ts';
+import { createRuntimeMcpApi } from './runtime-mcp-api.ts';
+import { createRuntimeOpsApi } from './runtime-ops-api.ts';
+import { createRuntimeProviderApi } from './runtime-provider-api.ts';
+import type { TaskManager } from '@pellux/goodvibes-sdk/platform/runtime/tasks/types';
+import { createDirectTransportFromServices, type DirectTransport } from './transports/direct.ts';
+import type { UiTasksSnapshot } from './ui-read-models.ts';
+
+export interface RuntimeFoundationClientsOptions extends OperatorClientServicesOptions {
+  readonly runtimeServices: RuntimeServices;
+  readonly tasksReadModel: {
+    getSnapshot(): UiTasksSnapshot;
+  };
+  readonly taskManager: TaskManager;
+  readonly opsControlPlane?: OpsControlPlane;
+}
+
+export interface RuntimeFoundationClients {
+  readonly transportServices: DirectTransportServices;
+  readonly directTransport: DirectTransport;
+  readonly providerApi: ProviderApi;
+  readonly knowledgeApi: KnowledgeApi;
+  readonly hookApi: HookApi;
+  readonly mcpApi: McpApi;
+  readonly opsApi: OpsApi;
+}
+
+export function createRuntimeFoundationClients(
+  options: RuntimeFoundationClientsOptions,
+): RuntimeFoundationClients {
+  const {
+    runtimeServices,
+    tasksReadModel,
+    taskManager,
+    opsControlPlane,
+    getControlPlaneRecentEvents,
+  } = options;
+
+  const transportServices = createDirectTransportServices(runtimeServices, {
+    ...(getControlPlaneRecentEvents ? { getControlPlaneRecentEvents } : {}),
+  });
+  const directTransport = createDirectTransportFromServices(transportServices);
+
+  return {
+    transportServices,
+    directTransport,
+    providerApi: createRuntimeProviderApi(runtimeServices),
+    knowledgeApi: createRuntimeKnowledgeApi(runtimeServices),
+    hookApi: createRuntimeHookApi({
+      dispatcher: {
+        listHooks: () => runtimeServices.hookDispatcher.listHooks(),
+        listChains: () => runtimeServices.hookWorkbench.listManagedChains(),
+      },
+      workbench: runtimeServices.hookWorkbench,
+      listContracts: () => listHookPointContracts(),
+    }),
+    mcpApi: createRuntimeMcpApi(runtimeServices.mcpRegistry),
+    opsApi: createRuntimeOpsApi({
+      tasksReadModel,
+      taskManager,
+      opsControlPlane,
+    }),
+  };
+}

package/src/runtime/foundation-services.ts

@@ -0,0 +1,96 @@
+import type { ApprovalBroker } from '../control-plane/approval-broker.ts';
+import type { SharedSessionBroker } from '../control-plane/session-broker.ts';
+import type { SecretsManager } from '../config/secrets.ts';
+import type { ServiceRegistry } from '../config/service-registry.ts';
+import type { SubscriptionManager } from '@pellux/goodvibes-sdk/platform/config/subscriptions';
+import type { ProviderRegistry } from '../providers/registry.ts';
+import type { RuntimeServices } from './services.ts';
+import type { ShellPathService } from '@pellux/goodvibes-sdk/platform/runtime/shell-paths';
+import type { UiRuntimeEvents } from './ui-events.ts';
+import { createUiRuntimeEvents } from './ui-events.ts';
+import { createCoreReadModels } from './ui-read-models-core.ts';
+import {
+  createOperationsReadModels,
+  type UiOperationsReadModelOptions,
+} from './ui-read-models-operations.ts';
+import type { PeerClientDependencies } from './peer-client.ts';
+
+export interface OperatorClientReadModels {
+  readonly controlPlane: ReturnType<typeof createOperationsReadModels>['controlPlane'];
+  readonly providers: ReturnType<typeof createCoreReadModels>['providers'];
+  readonly session: ReturnType<typeof createCoreReadModels>['session'];
+  readonly tasks: ReturnType<typeof createCoreReadModels>['tasks'];
+}
+
+export interface OperatorClientServices {
+  readonly events: UiRuntimeEvents;
+  readonly shellPaths: ShellPathService;
+  readonly readModels: OperatorClientReadModels;
+  readonly sessionBroker: SharedSessionBroker;
+  readonly approvalBroker: ApprovalBroker;
+  readonly providerRegistry: ProviderRegistry;
+  readonly serviceRegistry: ServiceRegistry;
+  readonly subscriptionManager: SubscriptionManager;
+  readonly secretsManager: SecretsManager;
+}
+
+export interface OperatorClientServicesOptions extends UiOperationsReadModelOptions {}
+
+export interface DirectTransportServices {
+  readonly operator: OperatorClientServices;
+  readonly peer: PeerClientDependencies;
+}
+
+function createOperatorClientReadModels(
+  runtimeServices: RuntimeServices,
+  options: OperatorClientServicesOptions = {},
+): OperatorClientReadModels {
+  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: RuntimeServices,
+  options: OperatorClientServicesOptions = {},
+): OperatorClientServices {
+  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: Pick<RuntimeServices, 'distributedRuntime' | 'remoteRunnerRegistry' | 'remoteSupervisor' | 'runtimeStore'>,
+): PeerClientDependencies {
+  return {
+    runtimeStore: runtimeServices.runtimeStore,
+    distributedRuntime: runtimeServices.distributedRuntime,
+    remoteRunnerRegistry: runtimeServices.remoteRunnerRegistry,
+    remoteSupervisor: runtimeServices.remoteSupervisor,
+  };
+}
+
+export interface DirectTransportServicesOptions extends OperatorClientServicesOptions {}
+
+export function createDirectTransportServices(
+  runtimeServices: RuntimeServices,
+  options: DirectTransportServicesOptions = {},
+): DirectTransportServices {
+  return {
+    operator: createOperatorClientServices(runtimeServices, options),
+    peer: createPeerClientDependencies(runtimeServices),
+  };
+}

package/src/runtime/guidance.ts

@@ -0,0 +1,183 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import type { ConfigManager } from '../config/manager.ts';
+import type { SessionMaintenanceStatus } from './session-maintenance.ts';
+import type { EcosystemRecommendation } from './ecosystem/recommendations.ts';
+
+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[];
+}
+
+interface GuidanceDismissalStore {
+  readonly version: 1;
+  readonly dismissed: Record<string, number>;
+}
+
+export interface GuidancePersistenceOptions {
+  readonly guidancePath?: string;
+  readonly userRoot?: string;
+  readonly homeDirectory?: string;
+}
+
+function resolveGuidancePath(options?: GuidancePersistenceOptions): string {
+  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', 'tui', 'guidance.json');
+}
+
+function readDismissals(options?: GuidancePersistenceOptions): GuidanceDismissalStore {
+  try {
+    const guidanceFile = resolveGuidancePath(options);
+    if (!existsSync(guidanceFile)) return { version: 1, dismissed: {} };
+    return JSON.parse(readFileSync(guidanceFile, 'utf-8')) as GuidanceDismissalStore;
+  } catch {
+    return { version: 1, dismissed: {} };
+  }
+}
+
+function writeDismissals(store: GuidanceDismissalStore, options?: GuidancePersistenceOptions): void {
+  const guidanceFile = resolveGuidancePath(options);
+  mkdirSync(dirname(guidanceFile), { recursive: true });
+  writeFileSync(guidanceFile, `${JSON.stringify(store, null, 2)}\n`, 'utf-8');
+}
+
+export function dismissGuidance(id: string, options?: GuidancePersistenceOptions): void {
+  const store = readDismissals(options);
+  store.dismissed[id] = Date.now();
+  writeDismissals(store, options);
+}
+
+export function resetGuidance(id?: string, options?: GuidancePersistenceOptions): void {
+  if (!id) {
+    writeDismissals({ version: 1, dismissed: {} }, options);
+    return;
+  }
+  const store = readDismissals(options);
+  delete store.dismissed[id];
+  writeDismissals(store, options);
+}
+
+export function evaluateContextualGuidance(
+  configManager: ConfigManager,
+  snapshot: ContextualGuidanceSnapshot,
+  maintenance: SessionMaintenanceStatus,
+  options?: GuidancePersistenceOptions,
+): GuidanceItem[] {
+  const mode = (configManager.get('behavior.guidanceMode') as GuidanceMode | undefined) ?? 'minimal';
+  if (mode === 'off') return [];
+
+  const dismissed = readDismissals(options).dismissed;
+  const items: GuidanceItem[] = [];
+
+  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: readonly GuidanceItem[]): string[] {
+  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/src/runtime/health/effect-handlers.ts

@@ -0,0 +1,189 @@
+/**
+ * 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 { createCascadeAppliedEvent } from '@pellux/goodvibes-sdk/platform/runtime/health/types';
+import type { RuntimeHealthAggregator } from '@pellux/goodvibes-sdk/platform/runtime/health/aggregator';
+import type { RuntimeEventBus, RuntimeEventEnvelope } from '../events/index.ts';
+import { createEventEnvelope } from '../events/index.ts';
+import type { AnyRuntimeEvent } from '../events/index.ts';
+
+/**
+ * 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: RuntimeEventBus,
+  envelope: RuntimeEventEnvelope<string, unknown>,
+): void {
+  bus.emit('session', envelope as unknown as RuntimeEventEnvelope<AnyRuntimeEvent['type'], AnyRuntimeEvent>);
+}
+
+/** 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 function handleCascadeEffect(
+  effect: CascadeEffect,
+  result: CascadeResult,
+  context: EffectHandlerContext,
+): void {
+  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'] as const)
+          : ([result.target] as const);
+
+      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: never = effect;
+      throw new Error(`Unhandled cascade effect type: ${(effect as { type: string }).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/src/runtime/health/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Runtime health monitoring system — barrel exports and factory.
+ *
+ * Usage:
+ * ```ts
+ * import { createHealthSystem } from './health/index.ts';
+ * 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.ts';
+export { handleCascadeEffect } from './effect-handlers.ts';
+export type { EffectHandlerContext } from './effect-handlers.ts';
+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 { CASCADE_RULES } from '@pellux/goodvibes-sdk/platform/runtime/health/cascade-rules';
+import { HealthStoreWiring } from './wiring.ts';
+
+/**
+ * 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(): {
+  aggregator: RuntimeHealthAggregator;
+  cascadeEngine: CascadeEngine;
+} {
+  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: import('../events/index.ts').RuntimeEventBus): {
+  aggregator: RuntimeHealthAggregator;
+  cascadeEngine: CascadeEngine;
+  wiring: HealthStoreWiring;
+} {
+  const aggregator = new RuntimeHealthAggregator();
+  const cascadeEngine = new CascadeEngine(CASCADE_RULES, aggregator);
+  const wiring = new HealthStoreWiring(aggregator, cascadeEngine, eventBus);
+  return { aggregator, cascadeEngine, wiring };
+}