@a-company/sentinel 0.2.0 → 3.6.0

package/dist/storage-BKyt7aPJ.d.ts

@@ -0,0 +1,319 @@
+import { l as CreateIncidentInput, a as SymbolicIncidentRecord, w as IncidentQueryOptions, v as IncidentNote, m as CreatePatternInput, e as FailurePattern, Z as PatternQueryOptions, k as CreateGroupInput, I as IncidentGroup, ab as ResolutionQueryOptions, ac as ResolutionRecord, b as SentinelStats, c as SymbolHealth, f as PatternExport, B as BackupExport, a5 as PracticeEventInput, a6 as PracticeEventQuery, a4 as PracticeEvent, y as LogEntryInput, G as LogQueryOptions, L as LogEntry, ag as ServiceRegistration, af as ServiceInfo, A as AppState, Q as MetricInput, R as MetricQueryOptions, O as MetricEntry, N as MetricAggregation, an as TraceSpanInput, ao as TraceView } from './types-BmVoO1iF.js';
+
+/**
+ * Schema Registry — Application-Agnostic Event Schema Types
+ *
+ * Applications register their own event schemas, and Sentinel ingests,
+ * stores, queries, and visualizes any structured event data.
+ */
+interface EventSchemaDeclaration {
+    /** Unique schema identifier, e.g. "pretend-engine", "paradigm-logger" */
+    id: string;
+    /** Schema version (semver) */
+    version: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Temporal grouping primitive */
+    scope: ScopeDeclaration;
+    /** Event type definitions */
+    eventTypes: EventTypeDeclaration[];
+    /** Causality tracking configuration */
+    causality?: CausalityDeclaration;
+    /** Visualization hints for the UI */
+    visualization?: VisualizationHints;
+    /** Classification tags */
+    tags?: string[];
+}
+interface ScopeDeclaration {
+    /** Field name for temporal grouping, e.g. "frame", "requestId", "tick" */
+    field: string;
+    /** Field type */
+    type: 'number' | 'string';
+    /** Human-readable label, e.g. "Frame", "Request" */
+    label: string;
+    /** Whether scopes are sequential (ordered) or independent */
+    ordering: 'sequential' | 'independent';
+    /** Optional session field for grouping scopes */
+    sessionField?: string;
+}
+interface EventTypeDeclaration {
+    /** Event type identifier, e.g. "rule:fire", "state:set" */
+    type: string;
+    /** Category for grouping, e.g. "rules", "state" */
+    category: string;
+    /** Human-readable label */
+    label?: string;
+    /** Description of what this event type represents */
+    description?: string;
+    /** Field declarations for event data */
+    fields?: EventFieldDeclaration[];
+    /** Expected frequency */
+    frequency?: 'high' | 'medium' | 'low';
+    /** Default severity level */
+    severity?: 'debug' | 'info' | 'warn' | 'error';
+}
+interface EventFieldDeclaration {
+    /** Field name */
+    name: string;
+    /** Field type */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Description */
+    description?: string;
+    /** Whether to create a database index on this field */
+    indexed?: boolean;
+    /** Whether to show this field in default table view */
+    display?: boolean;
+}
+interface CausalityDeclaration {
+    /** Field name for parent event reference */
+    parentField?: string;
+    /** Field for cascade depth, e.g. "pass" for cascade passes */
+    depthField?: string;
+    /** Event types that start a scope, e.g. ["tick:frame"] */
+    scopeStart?: string[];
+    /** Event types that end a scope, e.g. ["cascade:complete"] */
+    scopeEnd?: string[];
+}
+interface VisualizationHints {
+    /** Default view mode */
+    defaultView?: 'timeline' | 'table' | 'tree' | 'flame';
+    /** Category → color mapping */
+    categoryColors?: Record<string, string>;
+    /** Fields to show in summary/header */
+    summaryFields?: string[];
+    /** High-frequency event types hidden by default */
+    defaultExcluded?: string[];
+}
+interface GenericEvent {
+    /** Unique event ID */
+    id: string;
+    /** Schema this event belongs to */
+    schemaId: string;
+    /** Event type, e.g. "rule:fire" */
+    eventType: string;
+    /** Category, e.g. "rules" */
+    category: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Scope value (frame number, request ID, etc.) */
+    scopeValue?: string;
+    /** Numeric ordinal for sequential scopes */
+    scopeOrdinal?: number;
+    /** Session identifier */
+    sessionId?: string;
+    /** Service/app that emitted the event */
+    service: string;
+    /** Event-specific data */
+    data?: Record<string, unknown>;
+    /** Severity level */
+    severity?: 'debug' | 'info' | 'warn' | 'error';
+    /** Parent event ID for causality tracking */
+    parentEventId?: string;
+    /** Depth in causality tree */
+    depth?: number;
+}
+interface GenericEventInput {
+    /** Optional pre-assigned ID (auto-generated if omitted) */
+    id?: string;
+    /** Event type, e.g. "rule:fire" */
+    type: string;
+    /** ISO timestamp (auto-generated if omitted) */
+    timestamp?: string;
+    /** Scope value */
+    scopeValue?: string | number;
+    /** Session identifier */
+    sessionId?: string;
+    /** Event-specific data */
+    data?: Record<string, unknown>;
+    /** Severity override (resolved from schema defaults if omitted) */
+    severity?: 'debug' | 'info' | 'warn' | 'error';
+    /** Parent event ID */
+    parentEventId?: string;
+    /** Depth in causality tree */
+    depth?: number;
+}
+interface GenericEventQuery {
+    schemaId?: string;
+    eventType?: string;
+    category?: string;
+    service?: string;
+    sessionId?: string;
+    scopeValue?: string;
+    scopeFrom?: string;
+    scopeTo?: string;
+    severity?: string;
+    since?: string;
+    until?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ScopeSummary {
+    scopeValue: string;
+    scopeOrdinal?: number;
+    eventCount: number;
+    categories: Record<string, number>;
+    firstTimestamp: string;
+    lastTimestamp: string;
+}
+interface StoredSchema {
+    id: string;
+    version: string;
+    name: string;
+    description?: string;
+    scope: ScopeDeclaration;
+    eventTypes: EventTypeDeclaration[];
+    causality?: CausalityDeclaration;
+    visualization?: VisualizationHints;
+    tags: string[];
+    registeredAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Paradigm Sentinel - SQLite Storage Layer
+ *
+ * Persistent storage for incidents, patterns, groups, and resolutions.
+ * Uses sql.js for pure JavaScript SQLite (no native compilation needed).
+ */
+
+declare class SentinelStorage {
+    private db;
+    private dbPath;
+    private incidentCounter;
+    private initialized;
+    constructor(dbPath?: string);
+    private getDefaultDbPath;
+    private createSchema;
+    private save;
+    recordIncident(input: CreateIncidentInput): string;
+    private initializeSync;
+    /**
+     * Run schema migrations from older versions
+     */
+    private migrateSchema;
+    /**
+     * Ensure the storage is ready for use. Must be called once before using storage methods.
+     */
+    ensureReady(): Promise<void>;
+    getIncident(id: string): SymbolicIncidentRecord | null;
+    getRecentIncidents(options?: IncidentQueryOptions): SymbolicIncidentRecord[];
+    updateIncident(id: string, updates: Partial<SymbolicIncidentRecord>): void;
+    addIncidentNote(incidentId: string, note: Omit<IncidentNote, 'id'>): void;
+    linkIncidents(incidentId: string, relatedId: string): void;
+    getIncidentCount(options?: IncidentQueryOptions): number;
+    addPattern(input: CreatePatternInput): string;
+    getPattern(id: string): FailurePattern | null;
+    getAllPatterns(options?: PatternQueryOptions): FailurePattern[];
+    updatePattern(id: string, updates: Partial<FailurePattern>): void;
+    deletePattern(id: string): void;
+    updatePatternConfidence(patternId: string, event: 'matched' | 'resolved' | 'recurred'): void;
+    createGroup(input: CreateGroupInput): string;
+    getGroup(id: string): IncidentGroup | null;
+    getGroups(options?: {
+        limit?: number;
+    }): IncidentGroup[];
+    addToGroup(groupId: string, incidentId: string): void;
+    recordResolution(resolution: {
+        incidentId: string;
+        patternId?: string;
+        commitHash?: string;
+        prUrl?: string;
+        notes?: string;
+    }): void;
+    markRecurred(incidentId: string): void;
+    getResolutionHistory(options?: ResolutionQueryOptions): ResolutionRecord[];
+    getStats(period: {
+        start: string;
+        end: string;
+    }): SentinelStats;
+    getSymbolHealth(symbol: string): SymbolHealth;
+    exportPatterns(options?: {
+        includePrivate?: boolean;
+    }): PatternExport;
+    importPatterns(data: PatternExport, options?: {
+        overwrite?: boolean;
+    }): {
+        imported: number;
+        skipped: number;
+    };
+    exportBackup(): BackupExport;
+    importBackup(data: BackupExport): void;
+    private rowToIncident;
+    private rowToPattern;
+    private rowToGroup;
+    recordPracticeEvent(input: PracticeEventInput): string;
+    getPracticeEvents(options?: PracticeEventQuery): PracticeEvent[];
+    getPracticeEventCount(options?: PracticeEventQuery): number;
+    getComplianceRate(options?: PracticeEventQuery): {
+        total: number;
+        followed: number;
+        skipped: number;
+        partial: number;
+        rate: number;
+    };
+    private rowToPracticeEvent;
+    private inferSymbolType;
+    insertLog(input: LogEntryInput): string;
+    insertLogBatch(entries: LogEntryInput[]): {
+        accepted: number;
+        errors: string[];
+    };
+    queryLogs(options?: LogQueryOptions): LogEntry[];
+    getLogCount(options?: LogQueryOptions): number;
+    pruneLogs(maxCount: number): number;
+    private rowToLogEntry;
+    registerService(reg: ServiceRegistration): void;
+    updateServiceLastSeen(name: string): void;
+    getServices(): ServiceInfo[];
+    upsertAppState(state: AppState): void;
+    getAppState(service: string, sessionId?: string): AppState[];
+    getAllAppStates(): AppState[];
+    private rowToAppState;
+    insertMetric(input: MetricInput): string;
+    insertMetricBatch(entries: MetricInput[]): {
+        accepted: number;
+        errors: string[];
+    };
+    queryMetrics(options?: MetricQueryOptions): MetricEntry[];
+    getMetricCount(options?: MetricQueryOptions): number;
+    aggregateMetric(name: string, options?: {
+        service?: string;
+        since?: string;
+        until?: string;
+    }): MetricAggregation;
+    pruneMetrics(maxCount: number): number;
+    private rowToMetricEntry;
+    insertSpan(input: TraceSpanInput): string;
+    getTrace(traceId: string): TraceView | null;
+    queryTraces(options?: {
+        service?: string;
+        symbol?: string;
+        since?: string;
+        limit?: number;
+    }): TraceView[];
+    private rowToTraceSpan;
+    registerSchema(schema: EventSchemaDeclaration): StoredSchema;
+    getSchema(id: string): StoredSchema | null;
+    listSchemas(): StoredSchema[];
+    private rowToSchema;
+    insertEventBatch(schemaId: string, service: string, inputs: GenericEventInput[]): {
+        accepted: number;
+        errors: string[];
+    };
+    queryEvents(options?: GenericEventQuery): GenericEvent[];
+    queryEventsByScope(schemaId: string, scopeValue: string): GenericEvent[];
+    getEventScopes(schemaId: string, options?: {
+        limit?: number;
+        offset?: number;
+        sessionId?: string;
+    }): ScopeSummary[];
+    getEventCount(options?: GenericEventQuery): number;
+    pruneEvents(maxCount: number): number;
+    private rowToGenericEvent;
+    close(): void;
+}
+
+export { type CausalityDeclaration as C, type EventSchemaDeclaration as E, type GenericEvent as G, SentinelStorage as S, type VisualizationHints as V, type EventFieldDeclaration as a, type EventTypeDeclaration as b, type GenericEventInput as c, type GenericEventQuery as d, type ScopeDeclaration as e, type ScopeSummary as f, type StoredSchema as g };

package/dist/transport-DqamniUy.d.ts

@@ -0,0 +1,185 @@
+import { z as LogLevel, Q as MetricInput } from './types-BmVoO1iF.js';
+
+/**
+ * Sentinel Client SDK
+ *
+ * Lightweight client for sending structured logs to the Sentinel server.
+ * Features batching, ring buffer, auto-retry, and graceful degradation.
+ *
+ * Usage:
+ *   import { createSentinelClient } from '@a-company/sentinel';
+ *   const client = createSentinelClient({ service: 'my-app' });
+ *   client.info('#checkout', 'Order placed', { orderId: '123' });
+ *   await client.close();
+ */
+
+interface SentinelClientOptions {
+    /** Sentinel server URL (default: http://localhost:3838) */
+    url?: string;
+    /** Service name (required) */
+    service: string;
+    /** Service version */
+    version?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Auth token for protected servers */
+    token?: string;
+    /** Batch size before auto-flush (default: 50) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushIntervalMs?: number;
+    /** Max entries in ring buffer before dropping oldest (default: 1000) */
+    maxBufferSize?: number;
+    /** Max retry attempts on network failure (default: 3) */
+    maxRetries?: number;
+    /** Retry backoff base in ms (default: 1000) */
+    retryBackoffMs?: number;
+    /** Callback when entries are dropped from buffer overflow */
+    onDrop?: (count: number) => void;
+    /** Callback on flush error */
+    onError?: (error: Error) => void;
+}
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    end: (status?: 'ok' | 'error') => Promise<void>;
+}
+declare class SentinelClient {
+    private readonly url;
+    private readonly service;
+    private readonly version;
+    private readonly environment;
+    private readonly token;
+    private readonly batchSize;
+    private readonly maxBufferSize;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    private readonly onDrop;
+    private readonly onError;
+    private readonly sessionId;
+    private logBuffer;
+    private metricsBuffer;
+    private flushTimer;
+    private closed;
+    private beforeUnloadHandler;
+    constructor(options: SentinelClientOptions);
+    /** Log a debug-level message */
+    debug(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log an info-level message */
+    info(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log a warn-level message */
+    warn(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log an error-level message */
+    error(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log a message at the specified level */
+    log(level: LogLevel, symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Record a counter metric (increments) */
+    counter(name: string, value?: number, tags?: Record<string, string>): void;
+    /** Record a gauge metric (current value) */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /** Record a histogram metric (distribution) */
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    /** Record a metric of any type */
+    metric(input: Omit<MetricInput, 'service'>): void;
+    /** Push an application state snapshot to the server */
+    pushState(state: Record<string, unknown>, activeFlows?: string[], activeGates?: string[]): Promise<void>;
+    /** Start a trace span. Call end() on the returned SpanContext when the operation completes. */
+    startSpan(symbol: string, operation: string, parentSpanId?: string): SpanContext;
+    /** Flush all buffered logs and metrics to the server */
+    flush(): Promise<void>;
+    /** Flush remaining entries and shut down the client */
+    close(): Promise<void>;
+    /** Get the session ID assigned to this client instance */
+    getSessionId(): string;
+    /**
+     * Synchronous best-effort flush using sendBeacon (browser) or sync XHR fallback.
+     * Used in beforeunload where async is unreliable.
+     */
+    private flushSync;
+    /** Register this service with the Sentinel server (fire-and-forget) */
+    private registerService;
+    /** Push a log entry into the ring buffer, enforcing maxBufferSize */
+    private pushToLogBuffer;
+    /** Push a metric entry into the ring buffer, enforcing maxBufferSize */
+    private pushToMetricsBuffer;
+    /** Drain and return all entries from the log buffer */
+    private drainLogBuffer;
+    /** Drain and return all entries from the metrics buffer */
+    private drainMetricsBuffer;
+    /** Send log entries to the server with retry */
+    private sendLogs;
+    /** Send metric entries to the server with retry */
+    private sendMetrics;
+    /**
+     * POST JSON to the Sentinel server with exponential backoff retry.
+     * Retries on network errors and 5xx responses. Does NOT retry on 4xx.
+     */
+    private post;
+    /** Get the fetch function, falling back to globalThis.fetch */
+    private getFetch;
+    /** Wait with exponential backoff */
+    private backoff;
+    /** Handle an error, calling the onError callback if provided */
+    private handleError;
+}
+/**
+ * Create a new SentinelClient instance.
+ *
+ * Usage:
+ *   const client = createSentinelClient({ service: 'my-app', environment: 'production' });
+ *   client.info('#checkout', 'Order placed', { orderId: '123' });
+ */
+declare function createSentinelClient(options: SentinelClientOptions): SentinelClient;
+
+/**
+ * SentinelTransport — Bridge between Paradigm Logger and Sentinel Client
+ *
+ * Uses structural typing to match LogTransport interface without
+ * importing from @a-company/paradigm-logger (avoids hard dependency).
+ *
+ * Usage:
+ *   import { enableSentinel } from '@a-company/sentinel/transport';
+ *   import { log } from '@a-company/paradigm-logger';
+ *   enableSentinel(log, { service: 'my-app' });
+ */
+
+/** Structurally matches LogTransport.send() entry shape */
+interface LogEntry {
+    level: string;
+    symbol: string;
+    symbolType: string;
+    message: string;
+    data?: Record<string, unknown>;
+    correlationId?: string;
+    timestamp: string;
+}
+/** Structurally matches ParadigmLogger.addTransport() */
+interface LoggerWithTransports {
+    addTransport(transport: {
+        send(entry: LogEntry): void;
+    }): void;
+    removeTransport(transport: {
+        send(entry: LogEntry): void;
+    }): void;
+}
+declare class SentinelTransport {
+    readonly client: SentinelClient;
+    constructor(client: SentinelClient);
+    send(entry: LogEntry): void;
+}
+/**
+ * Create a SentinelTransport from an existing client or options.
+ *
+ *   const transport = createSentinelTransport(client);
+ *   log.addTransport(transport);
+ */
+declare function createSentinelTransport(clientOrOptions: SentinelClient | SentinelClientOptions): SentinelTransport;
+/**
+ * One-line setup: creates a SentinelTransport and attaches it to a logger.
+ *
+ *   import { log } from '@a-company/paradigm-logger';
+ *   const transport = enableSentinel(log, { service: 'my-app' });
+ */
+declare function enableSentinel(logger: LoggerWithTransports, clientOrOptions: SentinelClient | SentinelClientOptions): SentinelTransport;
+
+export { SentinelClient as S, type SentinelClientOptions as a, SentinelTransport as b, type SpanContext as c, createSentinelClient as d, createSentinelTransport as e, enableSentinel as f };

package/dist/transport.d.ts

@@ -0,0 +1,2 @@
+export { b as SentinelTransport, e as createSentinelTransport, f as enableSentinel } from './transport-DqamniUy.js';
+import './types-BmVoO1iF.js';

package/dist/transport.js

@@ -0,0 +1,10 @@
+import {
+  SentinelTransport,
+  createSentinelTransport,
+  enableSentinel
+} from "./chunk-VQ3SIN7S.js";
+export {
+  SentinelTransport,
+  createSentinelTransport,
+  enableSentinel
+};