@mikesaintsg/core 0.0.5 → 0.0.7

package/README.md

@@ -168,18 +168,31 @@ Implementation classes for cross-package bridges (also available via factory fun
 | `Ok<T>`, `Err<E>`                         | Result discriminants                  |
 | `Unsubscribe`                             | Cleanup function type                 |
 | `Destroyable`                             | Interface for resources with cleanup  |
+| `AbortableOptions`                        | Interface for cancellable operations  |
 | `SubscriptionToHook<T>`                   | Convert subscriptions to hooks        |
+| `ChangeSource`                            | Origin of state change (local/remote) |
+| `ContentHash`                             | SHA-256 hex string for deduplication  |
 | `Embedding`                               | Float32Array embedding vector         |
+| `EmbeddingModelMetadata`                  | Embedding model information           |
 | `ToolCall`, `ToolResult`, `ToolSchema`    | Tool-related types                    |
+| `Message`, `MessageRole`, `MessageContent`| Message types for inference           |
+| `GenerationOptions`, `GenerationResult`   | Generation configuration and result   |
 | `ScoredResult`                            | Search result with score              |
 | `ContextFrame`, `BuiltContext`            | Context management types              |
 | `TokenBudgetState`, `TokenBudgetLevel`    | Token budget types                    |
+| `Actor`, `EngagementState`                | ActionLoop shared types               |
+| `TransitionEvent`, `DwellRecord`          | Transition tracking types             |
+| `ModelTier`, `ModelInfo`                  | Model orchestration types             |
+| `StorageInfo`, `PruneResult`              | Storage utility types                 |
+| `HealthStatus`, `SystemHealth`            | Health check types                    |
+| `CircuitState`, `LifecycleState`          | System state types                    |
 
 ### Adapter Interfaces
 
 | Interface                                 | Category      | Description                    |
 |-------------------------------------------|---------------|--------------------------------|
 | `EmbeddingAdapterInterface`               | Source        | Embedding generation           |
+| `ProviderAdapterInterface`                | Source        | LLM provider integration       |
 | `ToolFormatAdapterInterface`              | Transform     | Provider tool formatting       |
 | `SimilarityAdapterInterface`              | Transform     | Vector similarity computation  |
 | `DeduplicationAdapterInterface`           | Transform     | Frame deduplication            |
@@ -187,10 +200,17 @@ Implementation classes for cross-package bridges (also available via factory fun
 | `PriorityAdapterInterface`                | Transform     | Frame priority ordering        |
 | `RetryAdapterInterface`                   | Policy        | Retry behavior                 |
 | `RateLimitAdapterInterface`               | Policy        | Rate limiting                  |
+| `CircuitBreakerAdapterInterface`          | Policy        | Cascading failure prevention   |
 | `EmbeddingCacheAdapterInterface`          | Enhancement   | Embedding caching              |
 | `BatchAdapterInterface`                   | Enhancement   | Batch processing               |
 | `RerankerAdapterInterface`                | Enhancement   | Result reranking               |
+| `TelemetryAdapterInterface`               | Observability | Monitoring and debugging       |
 | `VectorStorePersistenceAdapterInterface`  | Persistence   | Vector storage                 |
+| `SessionPersistenceInterface`             | Persistence   | Session storage                |
+| `EventStorePersistenceAdapterInterface`   | Persistence   | Transition event storage       |
+| `WeightPersistenceAdapterInterface`       | Persistence   | Predictive weight storage      |
+| `StreamerAdapterInterface`                | Streaming     | Token emission                 |
+| `SSEParserAdapterInterface`               | Streaming     | Server-sent events parsing     |
 
 ### Minimal Cross-Package Interfaces
 
@@ -204,6 +224,10 @@ Implementation classes for cross-package bridges (also available via factory fun
 | `VectorStoreMinimal<T>`     | Vector store without dependency      |
 | `FormMinimal<T>`            | Form state without dependency        |
 | `SerializableSession`       | Session serialization interface      |
+| `TokenCounterInterface`     | Token counting for models            |
+| `HealthCheckInterface`      | Health check for components          |
+| `ActivityTrackerInterface`  | User engagement tracking             |
+| `ShutdownManagerInterface`  | Graceful shutdown coordination       |
 
 ---
 

package/dist/index.d.ts

@@ -3,6 +3,16 @@ export declare interface AbortableOptions {
     readonly signal?: AbortSignal;
 }
 
+/** Activity metrics for a session */
+export declare interface ActivityMetrics {
+    readonly activeTimeMs: number;
+    readonly idleTimeMs: number;
+    readonly awayTimeMs: number;
+    readonly interactionCount: number;
+    readonly lastInteractionAt: number;
+    readonly sessionStartedAt: number;
+}
+
 /**
  * Activity tracker adapter interface.
  *
@@ -16,6 +26,12 @@ export declare interface ActivityTrackerInterface extends ActivityTrackerSubscri
     exitNode(): DwellRecord | undefined;
     /** Get current engagement state */
     getEngagementState(): EngagementState;
+    /** Get current visibility state */
+    getVisibilityState(): VisibilityState;
+    /** Get current focus state */
+    getFocusState(): FocusState;
+    /** Get activity metrics summary */
+    getMetrics(): ActivityMetrics;
     /** Get current node ID being tracked */
     getCurrentNodeId(): string | undefined;
     /** Get current incomplete dwell record */
@@ -26,6 +42,10 @@ export declare interface ActivityTrackerInterface extends ActivityTrackerSubscri
     getTotalActiveTime(): number;
     /** Get total idle time across all dwells */
     getTotalIdleTime(): number;
+    /** Record an interaction (resets idle timer) */
+    recordInteraction(): void;
+    /** Reset all tracking state */
+    reset(): void;
     /** Clear dwell history */
     clearHistory(): void;
 }
@@ -44,6 +64,12 @@ export declare interface ActivityTrackerOptions extends SubscriptionToHook<Activ
 export declare interface ActivityTrackerSubscriptions {
     /** Subscribe to engagement state changes */
     onEngagementChange(callback: (state: EngagementState, nodeId: string) => void): Unsubscribe;
+    /** Subscribe to visibility state changes */
+    onVisibilityChange(callback: (state: VisibilityState) => void): Unsubscribe;
+    /** Subscribe to focus state changes */
+    onFocusChange(callback: (state: FocusState) => void): Unsubscribe;
+    /** Subscribe to idle warnings before state changes to away */
+    onIdleWarning(callback: (idleTimeMs: number) => void): Unsubscribe;
     /** Subscribe to completed dwell records */
     onDwellComplete(callback: (record: DwellRecord) => void): Unsubscribe;
 }
@@ -51,6 +77,25 @@ export declare interface ActivityTrackerSubscriptions {
 /** Actor types for transition attribution */
 export declare type Actor = 'user' | 'system' | 'automation';
 
+/** Backpressure configuration */
+export declare interface BackpressureConfig {
+    readonly strategy: BackpressureStrategy;
+    readonly highWaterMark: number;
+    readonly lowWaterMark?: number;
+    readonly bufferSize?: number;
+}
+
+/** Backpressure state */
+export declare interface BackpressureState {
+    readonly currentSize: number;
+    readonly highWaterMark: number;
+    readonly isPaused: boolean;
+    readonly droppedCount: number;
+}
+
+/** Backpressure strategy */
+export declare type BackpressureStrategy = 'drop' | 'block' | 'buffer' | 'error';
+
 /**
  * Batch adapter interface.
  * Controls batching behavior for bulk operations.
@@ -107,6 +152,57 @@ export declare function chain<T, U, E>(result: Result<T, E>, fn: (value: T) => R
 /** Origin of state change */
 export declare type ChangeSource = 'local' | 'remote';
 
+/**
+ * Circuit breaker adapter interface.
+ * Prevents cascading failures by tracking error rates.
+ */
+export declare interface CircuitBreakerAdapterInterface extends CircuitBreakerSubscriptions {
+    /** Execute operation with circuit breaker protection */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /** Get current circuit state */
+    getState(): CircuitBreakerState;
+    /** Manually open the circuit */
+    open(): void;
+    /** Manually close the circuit */
+    close(): void;
+    /** Reset all counters and close circuit */
+    reset(): void;
+    /** Check if operation can proceed */
+    canExecute(): boolean;
+}
+
+/** Circuit breaker configuration */
+export declare interface CircuitBreakerConfig {
+    /** Failure threshold before opening circuit (default: 5) */
+    readonly failureThreshold: number;
+    /** Success threshold to close circuit from half-open (default: 3) */
+    readonly successThreshold: number;
+    /** Time in ms before attempting half-open (default: 30000) */
+    readonly resetTimeoutMs: number;
+    /** Time window for counting failures (default: 60000) */
+    readonly monitorWindowMs: number;
+}
+
+/** Circuit breaker state snapshot */
+export declare interface CircuitBreakerState {
+    readonly state: CircuitState;
+    readonly failureCount: number;
+    readonly successCount: number;
+    readonly lastFailureTime: number | undefined;
+    readonly lastSuccessTime: number | undefined;
+    readonly nextAttemptTime: number | undefined;
+}
+
+/** Circuit breaker subscriptions */
+export declare interface CircuitBreakerSubscriptions {
+    onStateChange(callback: (state: CircuitState, previous: CircuitState) => void): Unsubscribe;
+    onFailure(callback: (error: unknown, failureCount: number) => void): Unsubscribe;
+    onSuccess(callback: (successCount: number) => void): Unsubscribe;
+}
+
+/** Circuit breaker state */
+export declare type CircuitState = 'closed' | 'open' | 'half-open';
+
 /**
  * Compute a SHA-256 content hash for text.
  *
@@ -121,6 +217,41 @@ export declare type ChangeSource = 'local' | 'remote';
  */
 export declare function computeContentHash(text: string): Promise<ContentHash>;
 
+/** Configuration validation error */
+export declare interface ConfigValidationError {
+    readonly path: string;
+    readonly message: string;
+    readonly expected?: string;
+    readonly received?: string;
+}
+
+/** Configuration validation result */
+export declare interface ConfigValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ConfigValidationError[];
+    readonly warnings: readonly ConfigValidationWarning[];
+}
+
+/** Configuration validation warning */
+export declare interface ConfigValidationWarning {
+    readonly path: string;
+    readonly message: string;
+    readonly suggestion?: string;
+}
+
+/**
+ * Configuration validator interface.
+ * Validates configuration objects against expected schemas.
+ */
+export declare interface ConfigValidatorInterface<T> {
+    /** Validate configuration */
+    validate(config: unknown): ConfigValidationResult;
+    /** Get validated configuration or throw */
+    validateOrThrow(config: unknown): T;
+    /** Get default configuration */
+    getDefaults(): Partial<T>;
+}
+
 /** Content hash for deduplication (SHA-256 hex string) */
 export declare type ContentHash = string;
 
@@ -284,6 +415,9 @@ export declare interface Destroyable {
     destroy(): void;
 }
 
+/** Detected intent from user input */
+export declare type DetectedIntent = 'search' | 'question' | 'action' | 'navigation' | 'unclear';
+
 /** Dwell record capturing time spent on a node */
 export declare interface DwellRecord {
     readonly nodeId: string;
@@ -466,6 +600,9 @@ export declare interface ExportedWeight {
 /** Generation finish reason */
 export declare type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
 
+/** Focus state for activity tracking */
+export declare type FocusState = 'focused' | 'blurred';
+
 /** Default form dirty guard message */
 export declare const FORM_DIRTY_DEFAULT_MESSAGE = "You have unsaved changes. Are you sure you want to leave?";
 
@@ -567,6 +704,61 @@ export declare interface GenerationResult {
     readonly aborted: boolean;
 }
 
+/**
+ * Health check interface for system components.
+ * Implement this to enable health monitoring.
+ */
+export declare interface HealthCheckInterface {
+    /** Perform health check */
+    check(): Promise<HealthCheckResult>;
+    /** Get component name */
+    getName(): string;
+}
+
+/** Individual health check result */
+export declare interface HealthCheckResult {
+    readonly name: string;
+    readonly status: HealthStatus;
+    readonly message?: string;
+    readonly latencyMs?: number;
+    readonly timestamp: number;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+
+/** Health status for a component */
+export declare type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
+
+/** Histogram bucket for distribution metrics */
+export declare interface HistogramBucket {
+    readonly le: number;
+    readonly count: number;
+}
+
+/** Histogram metric data */
+export declare interface HistogramMetric {
+    readonly name: string;
+    readonly buckets: readonly HistogramBucket[];
+    readonly sum: number;
+    readonly count: number;
+    readonly labels?: Readonly<Record<string, string>>;
+}
+
+/** Intent detection result */
+export declare interface IntentDetectionResult {
+    readonly original: string;
+    readonly intent: DetectedIntent;
+    readonly confidence: number;
+    readonly refinedPrompt: string;
+    readonly processingTimeMs: number;
+    readonly modelTier: ModelTier;
+}
+
+/** Intent detector interface */
+export declare interface IntentDetectorInterface {
+    detect(input: string, options?: AbortableOptions): Promise<IntentDetectionResult>;
+    refine(input: string, intent: DetectedIntent, options?: AbortableOptions): Promise<string>;
+}
+
 /**
  * Type guard for ecosystem errors.
  *
@@ -654,6 +846,33 @@ export declare interface JSONSchema7 {
     readonly definitions?: Readonly<Record<string, JSONSchema7>>;
 }
 
+/**
+ * Lifecycle-aware component interface.
+ * Provides standardized lifecycle management.
+ */
+export declare interface LifecycleAwareInterface {
+    /** Get current lifecycle state */
+    getLifecycleState(): LifecycleState;
+    /** Subscribe to lifecycle state changes */
+    onLifecycleChange(callback: (state: LifecycleState, previous: LifecycleState) => void): Unsubscribe;
+    /** Check if component is ready for operations */
+    isReady(): boolean;
+}
+
+/** Component lifecycle state */
+export declare type LifecycleState = 'created' | 'initializing' | 'ready' | 'degraded' | 'stopping' | 'stopped' | 'error';
+
+/** Lifecycle state transition */
+export declare interface LifecycleTransition {
+    readonly from: LifecycleState;
+    readonly to: LifecycleState;
+    readonly timestamp: number;
+    readonly reason?: string;
+}
+
+/** Log level for telemetry */
+export declare type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
 /**
  * Map a function over a success value.
  *
@@ -706,6 +925,26 @@ export declare interface MessageMetadata {
 /** Message role */
 export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 
+/** Metric definition */
+export declare interface MetricDefinition {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly description: string;
+    readonly unit?: string;
+    readonly labels?: readonly string[];
+}
+
+/** Metric type discriminator */
+export declare type MetricType = 'counter' | 'gauge' | 'histogram' | 'summary';
+
+/** Recorded metric value */
+export declare interface MetricValue {
+    readonly name: string;
+    readonly value: number;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly timestamp: number;
+}
+
 /**
  * Minimal database access interface for cross-package adapters.
  * Used by persistence adapters to access IndexedDB without
@@ -750,6 +989,58 @@ export declare interface MinimalStoreAccess<T> {
     clear(): Promise<void>;
 }
 
+/** Model info for orchestration */
+export declare interface ModelInfo {
+    readonly tier: ModelTier;
+    readonly modelId: string;
+    readonly state: ModelLoadingState;
+    readonly loadProgress?: number;
+    readonly sizeBytes?: number;
+    readonly loadedAt?: number;
+}
+
+/** Model loading state */
+export declare type ModelLoadingState = 'idle' | 'loading' | 'ready' | 'error';
+
+/** Model orchestrator interface */
+export declare interface ModelOrchestratorInterface extends ModelOrchestratorSubscriptions, Destroyable {
+    getModelInfo(tier: ModelTier): ModelInfo | undefined;
+    isReady(tier: ModelTier): boolean;
+    getReadyTiers(): readonly ModelTier[];
+    getActiveTier(): ModelTier | undefined;
+    getBestAvailableTier(): ModelTier | undefined;
+    preload(tier: ModelTier): Promise<void>;
+    preloadAll(): Promise<void>;
+    estimateComplexity(prompt: string): number;
+    selectTier(complexity: number): ModelTier;
+    generate(prompt: string, options?: OrchestratorGenerateOptions): Promise<OrchestratorGenerateResult>;
+}
+
+/** Model orchestrator subscriptions */
+export declare interface ModelOrchestratorSubscriptions {
+    onModelStateChange(callback: (tier: ModelTier, state: ModelLoadingState) => void): Unsubscribe;
+    onModelSwitch(callback: (from: ModelTier, to: ModelTier, reason: string) => void): Unsubscribe;
+    onLoadProgress(callback: (tier: ModelTier, progress: number) => void): Unsubscribe;
+}
+
+/** Model selection strategy */
+export declare type ModelSelectionStrategy = 'auto' | 'local-only' | 'api-only' | 'local-first';
+
+/** Model tier for progressive loading */
+export declare type ModelTier = 'fast' | 'balanced' | 'powerful';
+
+/** Mutex for exclusive access */
+export declare interface MutexInterface {
+    /** Acquire the mutex, waiting if held */
+    acquire(): Promise<void>;
+    /** Release the mutex */
+    release(): void;
+    /** Check if mutex is currently held */
+    isLocked(): boolean;
+    /** Execute operation with mutex held */
+    withLock<T>(operation: () => Promise<T> | T): Promise<T>;
+}
+
 /**
  * Navigation guard function type.
  * Returns true to allow navigation, false to block.
@@ -777,6 +1068,27 @@ export declare interface Ok<T> {
  */
 export declare function ok<T>(value: T): Ok<T>;
 
+/** Model orchestrator generate options */
+export declare interface OrchestratorGenerateOptions extends AbortableOptions {
+    readonly forceTier?: ModelTier;
+    readonly system?: string;
+    readonly tools?: readonly ToolSchema[];
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+}
+
+/** Model orchestrator generate result */
+export declare interface OrchestratorGenerateResult {
+    readonly text: string;
+    readonly tier: ModelTier;
+    readonly modelId: string;
+    readonly latencyMs: number;
+    readonly tokenCount?: number;
+    readonly toolCalls?: readonly ToolCall[];
+    readonly escalated?: boolean;
+    readonly escalationReason?: string;
+}
+
 /**
  * Generic error data interface for package-specific errors.
  * Packages extend this to define their error structure.
@@ -973,6 +1285,20 @@ export declare interface ScoredResult {
     readonly embedding?: Embedding;
 }
 
+/** Semaphore for limiting concurrent operations */
+export declare interface SemaphoreInterface {
+    /** Acquire a permit, waiting if necessary */
+    acquire(): Promise<void>;
+    /** Try to acquire a permit without waiting */
+    tryAcquire(): boolean;
+    /** Release a permit */
+    release(): void;
+    /** Get number of available permits */
+    availablePermits(): number;
+    /** Get number of operations waiting for permits */
+    queueLength(): number;
+}
+
 /**
  * Minimal session interface for serialization.
  * Avoids hard dependency on inference package.
@@ -1060,6 +1386,53 @@ export declare interface SessionPersistenceOptions {
  */
 export declare function shouldSkipFormGuard<TPage extends string>(to: TPage, from: TPage, excludePages: readonly TPage[], onlyFromPages: readonly TPage[] | undefined): boolean;
 
+/** Shutdown handler registration */
+export declare interface ShutdownHandler {
+    readonly name: string;
+    readonly priority: ShutdownPriority;
+    readonly timeoutMs?: number;
+    readonly handler: () => Promise<void> | void;
+}
+
+/** Shutdown result for individual handler */
+export declare interface ShutdownHandlerResult {
+    readonly name: string;
+    readonly success: boolean;
+    readonly durationMs: number;
+    readonly error?: Error;
+}
+
+/**
+ * Graceful shutdown manager interface.
+ * Coordinates orderly shutdown of system components.
+ */
+export declare interface ShutdownManagerInterface {
+    /** Register a shutdown handler */
+    register(handler: ShutdownHandler): Unsubscribe;
+    /** Initiate graceful shutdown */
+    shutdown(timeoutMs?: number): Promise<ShutdownResult>;
+    /** Get current shutdown phase */
+    getPhase(): ShutdownPhase;
+    /** Check if shutdown is in progress */
+    isShuttingDown(): boolean;
+    /** Subscribe to phase changes */
+    onPhaseChange(callback: (phase: ShutdownPhase) => void): Unsubscribe;
+}
+
+/** Shutdown phase */
+export declare type ShutdownPhase = 'running' | 'draining' | 'stopping' | 'stopped';
+
+/** Shutdown handler priority */
+export declare type ShutdownPriority = 'first' | 'normal' | 'last';
+
+/** Overall shutdown result */
+export declare interface ShutdownResult {
+    readonly success: boolean;
+    readonly phase: ShutdownPhase;
+    readonly handlers: readonly ShutdownHandlerResult[];
+    readonly totalDurationMs: number;
+}
+
 /**
  * Similarity adapter interface.
  * Computes similarity between embedding vectors.
@@ -1205,6 +1578,53 @@ export declare type SubscriptionToHook<T> = {
     [K in keyof T]?: T[K] extends (callback: infer CB) => Unsubscribe ? CB : never;
 };
 
+/** Aggregated health status for a system */
+export declare interface SystemHealth {
+    readonly status: HealthStatus;
+    readonly checks: readonly HealthCheckResult[];
+    readonly timestamp: number;
+    readonly version?: string;
+}
+
+/**
+ * Telemetry adapter interface.
+ * Provides observability hooks for monitoring and debugging.
+ */
+export declare interface TelemetryAdapterInterface {
+    /** Start a new span for tracing */
+    startSpan(name: string, attributes?: Readonly<Record<string, unknown>>): TelemetrySpan;
+    /** End an active span */
+    endSpan(span: TelemetrySpan, status?: 'ok' | 'error'): void;
+    /** Record a log event */
+    log(level: LogLevel, message: string, attributes?: Readonly<Record<string, unknown>>): void;
+    /** Record a metric value */
+    recordMetric(name: string, value: number, attributes?: Readonly<Record<string, unknown>>): void;
+    /** Flush pending telemetry data */
+    flush(): Promise<void>;
+}
+
+/** Telemetry event for logging and metrics */
+export declare interface TelemetryEvent {
+    readonly timestamp: number;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly spanId?: string;
+    readonly traceId?: string;
+}
+
+/** Telemetry span for distributed tracing */
+export declare interface TelemetrySpan {
+    readonly id: string;
+    readonly traceId: string;
+    readonly parentId?: string;
+    readonly name: string;
+    readonly startTime: number;
+    readonly endTime?: number;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly status: 'ok' | 'error' | 'unset';
+}
+
 /** Timeout options for generation */
 export declare interface TimeoutOptions {
     readonly requestMs?: number;
@@ -1278,7 +1698,7 @@ export declare class ToolCallBridge implements ToolCallBridgeInterface {
 
 /**
  * Tool call bridge interface.
- * Connects inference tool calls to contextprotocol tool registry.
+ * Connects inference tool calls to contextbuilder tool registry.
  */
 export declare interface ToolCallBridgeInterface {
     /**
@@ -1324,7 +1744,7 @@ export declare interface ToolFormatAdapterInterface {
 
 /**
  * Minimal tool registry interface for bridge functions.
- * Avoids hard dependency on contextprotocol package.
+ * Avoids hard dependency on contextbuilder package.
  */
 export declare interface ToolRegistryMinimal {
     has(name: string): boolean;
@@ -1488,6 +1908,9 @@ export declare interface VectorStoreSearchOptions<TMetadata = unknown> {
     readonly filter?: TMetadata;
 }
 
+/** Visibility state for activity tracking */
+export declare type VisibilityState = 'visible' | 'hidden' | 'prerender';
+
 /**
  * Weight persistence adapter interface.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mikesaintsg/core",
-	"version": "0.0.5",
+	"version": "0.0.7",
 	"type": "module",
 	"description": "Shared types, contracts, and bridge functions for the @mikesaintsg ecosystem. Zero runtime dependencies.",
 	"keywords": [