@almadar/server 2.0.0 → 2.0.1

package/dist/deepagent/__tests__/memory.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Unit tests for MemoryManager integration
+ * @module @almadar/server/deepagent/memory.test
+ */
+export {};
+//# sourceMappingURL=memory.test.d.ts.map

package/dist/deepagent/__tests__/memory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.test.d.ts","sourceRoot":"","sources":["../../../src/deepagent/__tests__/memory.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/deepagent/__tests__/session.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Unit tests for SessionManager integration
+ * @module @almadar/server/deepagent/session.test
+ */
+export {};
+//# sourceMappingURL=session.test.d.ts.map

package/dist/deepagent/__tests__/session.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.test.d.ts","sourceRoot":"","sources":["../../../src/deepagent/__tests__/session.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/deepagent/__tests__/skill-agent.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Unit tests for skill agent factory
+ * @module @almadar/server/deepagent/skill-agent.test
+ */
+export {};
+//# sourceMappingURL=skill-agent.test.d.ts.map

package/dist/deepagent/__tests__/skill-agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-agent.test.d.ts","sourceRoot":"","sources":["../../../src/deepagent/__tests__/skill-agent.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/deepagent/memory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Memory Manager Singleton
+ *
+ * Provides Firestore-backed memory management for DeepAgent.
+ *
+ * @packageDocumentation
+ */
+import { MemoryManager } from '@almadar/agent';
+/**
+ * Get or create the MemoryManager singleton
+ */
+export declare function getMemoryManager(): MemoryManager;
+/**
+ * Reset the MemoryManager (useful for testing)
+ */
+export declare function resetMemoryManager(): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/deepagent/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/deepagent/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAK/C;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAehD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/deepagent/session.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Session Manager Singleton
+ *
+ * Provides Firestore-backed session management with full GAP features.
+ *
+ * @packageDocumentation
+ */
+import { SessionManager } from '@almadar/agent';
+/**
+ * Get or create the SessionManager singleton
+ */
+export declare function getSessionManager(): SessionManager;
+/**
+ * Reset the SessionManager (useful for testing)
+ */
+export declare function resetSessionManager(): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/deepagent/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/deepagent/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAchD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAclD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/deepagent/skill-agent.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Skill Agent Factory
+ *
+ * Creates DeepAgent instances with full GAP feature integration.
+ *
+ * @packageDocumentation
+ */
+import { type SkillAgentOptions, type SkillAgentResult } from '@almadar/agent';
+import { getMemoryManager } from './memory.js';
+import { getSessionManager } from './session.js';
+interface ServerSkillAgentOptions extends SkillAgentOptions {
+    /** User ID from Firebase Auth */
+    userId: string;
+    /** App/Project ID for context */
+    appId?: string;
+}
+/**
+ * Create a skill agent with full server-side GAP integration
+ */
+export declare function createServerSkillAgent(options: ServerSkillAgentOptions): Promise<SkillAgentResult>;
+export { getMemoryManager, getSessionManager };
+//# sourceMappingURL=skill-agent.d.ts.map

package/dist/deepagent/skill-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-agent.d.ts","sourceRoot":"","sources":["../../src/deepagent/skill-agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,UAAU,uBAAwB,SAAQ,iBAAiB;IACzD,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,gBAAgB,CAAC,CAsD3B;AAGD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @almadar/server - Shared server infrastructure for Almadar applications
+ *
+ * This package provides:
+ * - Database utilities (Firebase/Firestore)
+ * - Event bus for cross-trait communication
+ * - Express middleware (auth, error handling, validation)
+ * - Data services (mock and production)
+ * - Query filter utilities
+ *
+ * @packageDocumentation
+ */
+export { env } from './lib/env.js';
+export { logger } from './lib/logger.js';
+export { EventBus, serverEventBus, emitEntityEvent, type EventLogEntry } from './lib/eventBus.js';
+export { DistributedEventBus, InMemoryTransport, RedisTransport, type IEventBusTransport, type TransportMessage, type TransportReceiver, type RedisTransportOptions, } from './lib/eventBusTransport.js';
+export { EventPersistence, InMemoryEventStore, type PersistedEvent, type EventQuery, type EventPersistenceOptions, type IEventStore, } from './lib/eventPersistence.js';
+export { debugEventsRouter } from './lib/debugRouter.js';
+export { initializeFirebase, getFirestore, getAuth, admin, db } from './lib/db.js';
+export { setupEventBroadcast, getWebSocketServer, closeWebSocketServer, getConnectedClientCount, } from './lib/websocket.js';
+export { errorHandler, notFoundHandler, asyncHandler, AppError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError, } from './middleware/errorHandler.js';
+export { validateBody, validateQuery, validateParams } from './middleware/validation.js';
+export { authenticateFirebase } from './middleware/authenticateFirebase.js';
+export { mockDataService, MockDataService, type FieldSchema, type EntitySchema, } from './services/MockDataService.js';
+export { dataService, seedMockData, type DataService, type EntitySeedConfig, type PaginationOptions, type PaginatedResult, } from './services/DataService.js';
+export { toFirestoreFormat, fromFirestoreFormat, SchemaStore, SnapshotStore, ChangeSetStore, ValidationStore, SchemaProtectionService, } from './stores/index.js';
+export { parseQueryFilters, applyFiltersToQuery, extractPaginationParams, type ParsedFilter, type FirestoreWhereFilterOp, type PaginationParams, } from './utils/queryFilters.js';
+export { getMemoryManager, resetMemoryManager, } from './deepagent/memory.js';
+export { getSessionManager, resetSessionManager, } from './deepagent/session.js';
+export { createServerSkillAgent, getMemoryManager as getAgentMemoryManager, getSessionManager as getAgentSessionManager, } from './deepagent/skill-agent.js';
+export { multiUserMiddleware, verifyFirebaseAuth, } from './middleware/multi-user.js';
+export { setupStateSyncWebSocket } from './websocket/state-sync.js';
+export { ServiceDiscovery, InMemoryServiceRegistry, type ServiceRegistration, type ServiceRegistryOptions, type IServiceRegistry, } from './lib/serviceDiscovery.js';
+export { default as observabilityRouter } from './routes/observability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClG,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,WAAW,GACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAG5E,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,WAAW,EACX,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,cAAc,EACd,eAAe,EACf,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,sBAAsB,EACtB,gBAAgB,IAAI,qBAAqB,EACzC,iBAAiB,IAAI,sBAAsB,GAC5C,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACL,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAGpE,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/lib/db.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Database Accessors & Initialization
+ *
+ * This module provides:
+ * - `initializeFirebase()` — convenience function to init Firebase from env vars
+ * - `getFirestore()`, `getAuth()` — accessors for Firebase services
+ * - `db` — lazy Firestore proxy (no eager initialization)
+ *
+ * The consuming application MUST call `initializeFirebase()` or
+ * `admin.initializeApp()` before using any Firebase-dependent features.
+ */
+import admin from 'firebase-admin';
+/**
+ * Initialize Firebase Admin SDK from environment variables.
+ *
+ * Reads: FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY,
+ *        FIREBASE_SERVICE_ACCOUNT_PATH, FIRESTORE_EMULATOR_HOST
+ *
+ * Safe to call multiple times — returns existing app if already initialized.
+ */
+export declare function initializeFirebase(): admin.app.App;
+/**
+ * Get Firestore instance from the pre-initialized Firebase app.
+ */
+export declare function getFirestore(): admin.firestore.Firestore;
+/**
+ * Get Firebase Auth instance from the pre-initialized Firebase app.
+ */
+export declare function getAuth(): admin.auth.Auth;
+export { admin };
+/**
+ * Lazy Firestore proxy — resolves on first property access, not at import time.
+ * This prevents the "Firebase not initialized" error during module loading.
+ */
+export declare const db: admin.firestore.Firestore;
+//# sourceMappingURL=db.d.ts.map

package/dist/lib/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/lib/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,gBAAgB,CAAC;AAEnC;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAwDlD;AAgBD;;GAEG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAAC,SAAS,CAAC,SAAS,CAExD;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAEzC;AAGD,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB;;;GAGG;AACH,eAAO,MAAM,EAAE,2BAMb,CAAC"}

package/dist/lib/debugRouter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Debug Events Router
+ *
+ * Provides diagnostic endpoints for inspecting the server EventBus.
+ * Only active when NODE_ENV=development.
+ *
+ * Endpoints:
+ *   GET    /event-log   - Recent emitted events with listener counts
+ *   DELETE /event-log   - Clear the event log
+ *   GET    /listeners   - Registered listener counts per event
+ *
+ * @packageDocumentation
+ */
+import { Router } from 'express';
+/**
+ * Creates an Express router with debug endpoints for the server EventBus.
+ * Returns a no-op router in production (no routes registered).
+ */
+export declare function debugEventsRouter(): Router;
+//# sourceMappingURL=debugRouter.d.ts.map

package/dist/lib/debugRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugRouter.d.ts","sourceRoot":"","sources":["../../src/lib/debugRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAGjC;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAyB1C"}

package/dist/lib/env.d.ts

@@ -0,0 +1,16 @@
+export declare const env: {
+    NODE_ENV: "development" | "production" | "test";
+    PORT: number;
+    CORS_ORIGIN: string | string[];
+    API_PREFIX: string;
+    USE_MOCK_DATA: boolean;
+    DATABASE_URL?: string | undefined;
+    FIREBASE_PROJECT_ID?: string | undefined;
+    FIREBASE_CLIENT_EMAIL?: string | undefined;
+    FIREBASE_PRIVATE_KEY?: string | undefined;
+    FIREBASE_SERVICE_ACCOUNT_PATH?: string | undefined;
+    FIRESTORE_EMULATOR_HOST?: string | undefined;
+    FIREBASE_AUTH_EMULATOR_HOST?: string | undefined;
+    MOCK_SEED?: number | undefined;
+};
+//# sourceMappingURL=env.d.ts.map

package/dist/lib/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AA8CA,eAAO,MAAM,GAAG;;;;;;;;;;;;;;CAAc,CAAC"}

package/dist/lib/eventBus.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Server EventBus - Singleton for server-side cross-trait communication
+ *
+ * This EventBus enables:
+ * - Server-side trait event emission after CRUD operations
+ * - Server-side trait listeners responding to events
+ * - Cross-client event broadcast via WebSocket
+ *
+ * @packageDocumentation
+ */
+type EventHandler = (payload: unknown, meta?: Record<string, unknown>) => void;
+export interface EventLogEntry {
+    event: string;
+    payload: unknown;
+    timestamp: number;
+    listenerCount: number;
+    wildcardListenerCount: number;
+}
+/**
+ * Simple EventBus implementation for server-side events
+ */
+export declare class EventBus {
+    private handlers;
+    private debug;
+    private eventLog;
+    constructor(options?: {
+        debug?: boolean;
+    });
+    on(event: string, handler: EventHandler): () => void;
+    off(event: string, handler: EventHandler): void;
+    emit(event: string, payload?: unknown, meta?: Record<string, unknown>): void;
+    getRecentEvents(limit?: number): EventLogEntry[];
+    clearEventLog(): void;
+    getListenerCounts(): Record<string, number>;
+    clear(): void;
+}
+/**
+ * Singleton EventBus instance for server-side event communication.
+ */
+export declare const serverEventBus: EventBus;
+/**
+ * Type-safe event emission helper
+ */
+export declare function emitEntityEvent(entityType: string, action: 'CREATED' | 'UPDATED' | 'DELETED', payload: Record<string, unknown>): void;
+export {};
+//# sourceMappingURL=eventBus.d.ts.map

package/dist/lib/eventBus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBus.d.ts","sourceRoot":"","sources":["../../src/lib/eventBus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE/E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAID;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAA6C;IAC7D,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IAIzC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI;IAYpD,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAI/C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAgD5E,eAAe,CAAC,KAAK,SAAK,GAAG,aAAa,EAAE;IAI5C,aAAa,IAAI,IAAI;IAIrB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQ3C,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,UAEzB,CAAC;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAGN"}

package/dist/lib/eventBusTransport.d.ts

@@ -0,0 +1,143 @@
+/**
+ * EventBus Transport Layer — Pluggable backends for distributed event communication
+ *
+ * Transports enable emit/listen to work across processes:
+ * - InMemoryTransport: Default, same-process (no-op relay)
+ * - RedisTransport: Redis pub/sub for cross-process communication
+ *
+ * The DistributedEventBus wraps the existing EventBus and relays events
+ * through a transport. Local listeners still fire immediately; the transport
+ * handles cross-process delivery.
+ *
+ * @packageDocumentation
+ */
+import { type EventLogEntry } from './eventBus.js';
+/**
+ * Message shape sent over the transport wire.
+ */
+export interface TransportMessage {
+    event: string;
+    payload: unknown;
+    meta?: Record<string, unknown>;
+    /** Source instance ID to prevent echo loops */
+    sourceId: string;
+    timestamp: number;
+}
+/**
+ * Callback invoked when a message arrives from another process.
+ */
+export type TransportReceiver = (message: TransportMessage) => void;
+/**
+ * Pluggable transport interface for cross-process event delivery.
+ */
+export interface IEventBusTransport {
+    /** Publish a message to the transport */
+    publish(message: TransportMessage): Promise<void>;
+    /** Subscribe to incoming messages from other processes */
+    subscribe(receiver: TransportReceiver): Promise<void>;
+    /** Unsubscribe and clean up resources */
+    close(): Promise<void>;
+}
+/**
+ * No-op transport for single-process mode.
+ * Events stay in the local EventBus only.
+ */
+export declare class InMemoryTransport implements IEventBusTransport {
+    publish(): Promise<void>;
+    subscribe(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Options for RedisTransport.
+ */
+export interface RedisTransportOptions {
+    /** Redis channel name for event relay (default: 'almadar:events') */
+    channel?: string;
+    /**
+     * Publish function — sends serialized message to Redis channel.
+     * This is injected so we don't depend on a specific Redis client library.
+     */
+    publishFn: (channel: string, message: string) => Promise<void>;
+    /**
+     * Subscribe function — registers a callback for messages on a Redis channel.
+     * This is injected so we don't depend on a specific Redis client library.
+     */
+    subscribeFn: (channel: string, callback: (message: string) => void) => Promise<void>;
+    /**
+     * Unsubscribe/cleanup function.
+     */
+    closeFn?: () => Promise<void>;
+}
+/**
+ * Redis pub/sub transport for cross-process event delivery.
+ *
+ * Uses dependency-injected publish/subscribe functions so the transport
+ * is not coupled to any specific Redis client library (ioredis, redis, etc.).
+ *
+ * Usage with ioredis:
+ * ```typescript
+ * import Redis from 'ioredis';
+ * const pub = new Redis(process.env.REDIS_URL);
+ * const sub = new Redis(process.env.REDIS_URL);
+ *
+ * const transport = new RedisTransport({
+ *   publishFn: (ch, msg) => pub.publish(ch, msg).then(() => {}),
+ *   subscribeFn: (ch, cb) => { sub.subscribe(ch); sub.on('message', (_, msg) => cb(msg)); return Promise.resolve(); },
+ *   closeFn: async () => { await pub.quit(); await sub.quit(); },
+ * });
+ * ```
+ */
+export declare class RedisTransport implements IEventBusTransport {
+    private channel;
+    private publishFn;
+    private subscribeFn;
+    private closeFn;
+    constructor(options: RedisTransportOptions);
+    publish(message: TransportMessage): Promise<void>;
+    subscribe(receiver: TransportReceiver): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * DistributedEventBus wraps the existing EventBus and relays events
+ * through a pluggable transport for cross-process communication.
+ *
+ * - Local emit → fires local listeners + publishes to transport
+ * - Transport message received → fires local listeners (skips re-publish)
+ *
+ * Drop-in replacement for EventBus — same API, same singleton pattern.
+ */
+export declare class DistributedEventBus {
+    private localBus;
+    private transport;
+    private instanceId;
+    private isRelaying;
+    constructor(options?: {
+        debug?: boolean;
+        transport?: IEventBusTransport;
+    });
+    /**
+     * Initialize the transport subscription. Call once at startup.
+     */
+    connect(): Promise<void>;
+    /**
+     * Emit an event locally and publish to transport for other processes.
+     */
+    emit(event: string, payload?: unknown, meta?: Record<string, unknown>): void;
+    /** Subscribe to an event */
+    on(event: string, handler: (payload: unknown, meta?: Record<string, unknown>) => void): () => void;
+    /** Unsubscribe from an event */
+    off(event: string, handler: (payload: unknown, meta?: Record<string, unknown>) => void): void;
+    /** Get recent events (dev diagnostics) */
+    getRecentEvents(limit?: number): EventLogEntry[];
+    /** Clear event log */
+    clearEventLog(): void;
+    /** Get listener counts */
+    getListenerCounts(): Record<string, number>;
+    /** Clear all listeners and log */
+    clear(): void;
+    /** Disconnect transport */
+    disconnect(): Promise<void>;
+    /** Get the instance ID (for debugging) */
+    getInstanceId(): string;
+}
+//# sourceMappingURL=eventBusTransport.d.ts.map

package/dist/lib/eventBusTransport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventBusTransport.d.ts","sourceRoot":"","sources":["../../src/lib/eventBusTransport.ts"],"names":[],"mappings":"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"}

package/dist/lib/eventPersistence.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Event Persistence Layer — Optional durable event storage for replay and debugging
+ *
+ * Wraps the EventBus to persist emitted events. Supports:
+ * - In-memory storage (default, for development)
+ * - Configurable retention (TTL-based cleanup)
+ * - Replay API: query events by name, time range, or source
+ * - Required for saga compensation and distributed debugging
+ *
+ * @packageDocumentation
+ */
+/** Persisted event record */
+export interface PersistedEvent {
+    /** Unique event ID */
+    id: string;
+    /** Event name (e.g., 'LLM_RESPONSE') */
+    eventName: string;
+    /** Event payload */
+    payload: unknown;
+    /** Source orbital/service that emitted this event */
+    source: string;
+    /** Timestamp when event was emitted */
+    timestamp: number;
+    /** Trace ID for distributed tracing correlation */
+    traceId: string;
+    /** Optional metadata */
+    meta?: Record<string, unknown>;
+}
+/** Query filters for replaying events */
+export interface EventQuery {
+    /** Filter by event name (exact match) */
+    eventName?: string;
+    /** Filter by source orbital */
+    source?: string;
+    /** Filter by trace ID */
+    traceId?: string;
+    /** Events after this timestamp */
+    after?: number;
+    /** Events before this timestamp */
+    before?: number;
+    /** Maximum number of events to return */
+    limit?: number;
+    /** Sort order */
+    order?: 'asc' | 'desc';
+}
+/** Options for the event persistence layer */
+export interface EventPersistenceOptions {
+    /** Whether persistence is enabled (default: true) */
+    enabled?: boolean;
+    /** TTL in milliseconds for event retention (default: 24 hours) */
+    retentionMs?: number;
+    /** Maximum events to store (default: 10000) */
+    maxEvents?: number;
+    /** Cleanup interval in milliseconds (default: 5 minutes) */
+    cleanupIntervalMs?: number;
+    /** Default source identifier */
+    defaultSource?: string;
+}
+/** Storage backend interface */
+export interface IEventStore {
+    /** Persist an event */
+    store(event: PersistedEvent): Promise<void>;
+    /** Query events */
+    query(filters: EventQuery): Promise<PersistedEvent[]>;
+    /** Get a single event by ID */
+    get(id: string): Promise<PersistedEvent | null>;
+    /** Delete events older than timestamp */
+    deleteOlderThan(timestamp: number): Promise<number>;
+    /** Get total event count */
+    count(): Promise<number>;
+    /** Clear all stored events */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory event store for development and testing.
+ */
+export declare class InMemoryEventStore implements IEventStore {
+    private events;
+    private index;
+    store(event: PersistedEvent): Promise<void>;
+    query(filters: EventQuery): Promise<PersistedEvent[]>;
+    get(id: string): Promise<PersistedEvent | null>;
+    deleteOlderThan(timestamp: number): Promise<number>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+}
+/**
+ * Event persistence layer that can be attached to an EventBus.
+ *
+ * Usage:
+ * ```typescript
+ * const persistence = new EventPersistence({ retentionMs: 3600000 });
+ * persistence.startCleanup();
+ *
+ * // Persist an event
+ * await persistence.persist('LLM_RESPONSE', { content: '...' }, { source: 'llm-service' });
+ *
+ * // Replay events
+ * const events = await persistence.replay({ eventName: 'LLM_RESPONSE', limit: 10 });
+ *
+ * // Stop cleanup on shutdown
+ * persistence.stopCleanup();
+ * ```
+ */
+export declare class EventPersistence {
+    private store;
+    private options;
+    private cleanupTimer;
+    constructor(options?: EventPersistenceOptions, store?: IEventStore);
+    /**
+     * Persist an event.
+     */
+    persist(eventName: string, payload: unknown, meta?: {
+        source?: string;
+        traceId?: string;
+        [key: string]: unknown;
+    }): Promise<PersistedEvent>;
+    /**
+     * Replay events matching the query filters.
+     */
+    replay(query: EventQuery): Promise<PersistedEvent[]>;
+    /**
+     * Get a single event by ID.
+     */
+    getEvent(id: string): Promise<PersistedEvent | null>;
+    /**
+     * Get event count.
+     */
+    getEventCount(): Promise<number>;
+    /**
+     * Run cleanup — delete events older than retention period.
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Start periodic cleanup timer.
+     */
+    startCleanup(): void;
+    /**
+     * Stop periodic cleanup timer.
+     */
+    stopCleanup(): void;
+    /**
+     * Clear all persisted events.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the underlying store (for testing or custom queries).
+     */
+    getStore(): IEventStore;
+}
+//# sourceMappingURL=eventPersistence.d.ts.map

package/dist/lib/eventPersistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventPersistence.d.ts","sourceRoot":"","sources":["../../src/lib/eventPersistence.ts"],"names":[],"mappings":"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"}

package/dist/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { env } from './env.js';
+export { getFirestore, getAuth, admin } from './db.js';
+export { logger } from './logger.js';
+export { serverEventBus, emitEntityEvent } from './eventBus.js';
+export { setupEventBroadcast, getWebSocketServer, closeWebSocketServer, getConnectedClientCount, } from './websocket.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC"}

package/dist/lib/logger.d.ts

@@ -0,0 +1,7 @@
+export declare const logger: {
+    debug: (message: string, meta?: unknown) => void;
+    info: (message: string, meta?: unknown) => void;
+    warn: (message: string, meta?: unknown) => void;
+    error: (message: string, meta?: unknown) => void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/lib/logger.ts"],"names":[],"mappings":"AA0BA,eAAO,MAAM,MAAM;qBACA,MAAM,SAAS,OAAO;oBAKvB,MAAM,SAAS,OAAO;oBAKtB,MAAM,SAAS,OAAO;qBAKrB,MAAM,SAAS,OAAO;CAKxC,CAAC"}