@a-company/sentinel 0.2.0

package/dist/sdk-B27_vK1g.d.ts

@@ -0,0 +1,644 @@
+/**
+ * Paradigm Sentinel - Type Definitions
+ *
+ * Comprehensive types for semantic incident recording, pattern matching,
+ * and failure triage.
+ */
+type IncidentStatus = 'open' | 'investigating' | 'resolved' | 'wont-fix';
+type Environment = 'production' | 'staging' | 'development' | 'test' | string;
+interface ErrorDetails {
+    message: string;
+    stack?: string;
+    code?: string;
+    type?: string;
+}
+/**
+ * Symbolic context for incidents
+ *
+ * v2 Note: feature, state, and integration are now #component with tags.
+ * These fields are kept for backward compatibility with existing incidents.
+ * New incidents should use 'component' with appropriate tags.
+ */
+interface SymbolicContext {
+    /** @deprecated v2: Use component with tags: [feature] */
+    feature?: string;
+    component?: string;
+    flow?: string;
+    gate?: string;
+    signal?: string;
+    /** @deprecated v2: Use component with tags: [state] */
+    state?: string;
+    /** @deprecated v2: Use component with tags: [integration] */
+    integration?: string;
+}
+interface FlowPosition {
+    flowId: string;
+    expected: string[];
+    actual: string[];
+    missing: string[];
+    failedAt?: string;
+}
+interface IncidentNote {
+    id: string;
+    timestamp: string;
+    author?: string;
+    content: string;
+}
+interface Resolution {
+    patternId?: string;
+    commitHash?: string;
+    prUrl?: string;
+    notes?: string;
+}
+interface SymbolicIncidentRecord {
+    id: string;
+    timestamp: string;
+    status: IncidentStatus;
+    error: ErrorDetails;
+    symbols: SymbolicContext;
+    flowPosition?: FlowPosition;
+    environment: Environment;
+    service?: string;
+    version?: string;
+    userId?: string;
+    requestId?: string;
+    groupId?: string;
+    notes: IncidentNote[];
+    relatedIncidents: string[];
+    resolvedAt?: string;
+    resolvedBy?: string;
+    resolution?: Resolution;
+}
+type CreateIncidentInput = Omit<SymbolicIncidentRecord, 'id' | 'notes' | 'relatedIncidents' | 'timestamp' | 'status'> & {
+    timestamp?: string;
+    status?: IncidentStatus;
+};
+type PatternSource = 'manual' | 'suggested' | 'imported' | 'community';
+type ResolutionStrategy = 'retry' | 'fallback' | 'fix-data' | 'fix-code' | 'ignore' | 'escalate';
+type PatternPriority = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Symbol criteria for pattern matching
+ *
+ * v2 Note: feature, state, and integration are now #component with tags.
+ * These fields are kept for backward compatibility with existing patterns.
+ */
+interface PatternSymbolCriteria {
+    /** @deprecated v2: Use component with tags filter */
+    feature?: string | string[];
+    component?: string | string[];
+    flow?: string | string[];
+    gate?: string | string[];
+    signal?: string | string[];
+    /** @deprecated v2: Use component with tags filter */
+    state?: string | string[];
+    /** @deprecated v2: Use component with tags filter */
+    integration?: string | string[];
+    /** v2: Filter by tags instead of legacy symbol types */
+    tags?: string | string[];
+}
+interface PatternCriteria {
+    symbols: PatternSymbolCriteria;
+    errorContains?: string[];
+    errorMatches?: string;
+    errorType?: string[];
+    missingSignals?: string[];
+    environment?: string[];
+}
+interface PatternResolution {
+    description: string;
+    strategy: ResolutionStrategy;
+    priority: PatternPriority;
+    codeHint?: string;
+    codeSnippet?: string;
+    symbolsToModify?: string[];
+    filesLikelyInvolved?: string[];
+    commitRef?: string;
+    prRef?: string;
+    docsRef?: string;
+}
+interface PatternConfidence {
+    score: number;
+    timesMatched: number;
+    timesResolved: number;
+    timesRecurred: number;
+    avgTimeToResolve?: number;
+    lastMatched?: string;
+    lastResolved?: string;
+}
+interface FailurePattern {
+    id: string;
+    name: string;
+    description: string;
+    pattern: PatternCriteria;
+    resolution: PatternResolution;
+    confidence: PatternConfidence;
+    source: PatternSource;
+    private: boolean;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+type CreatePatternInput = Omit<FailurePattern, 'confidence' | 'createdAt' | 'updatedAt'> & {
+    confidence?: Partial<PatternConfidence>;
+};
+interface MatchedCriteria {
+    symbols: string[];
+    errorKeywords: string[];
+    missingSignals: string[];
+}
+interface PatternMatch {
+    pattern: FailurePattern;
+    score: number;
+    matchedCriteria: MatchedCriteria;
+    confidence: number;
+}
+interface MatcherConfig {
+    minScore: number;
+    maxResults: number;
+    boostConfidence: boolean;
+}
+interface IncidentGroup {
+    id: string;
+    name?: string;
+    incidents: string[];
+    commonSymbols: Partial<SymbolicContext>;
+    commonErrorPatterns: string[];
+    count: number;
+    firstSeen: string;
+    lastSeen: string;
+    environments: string[];
+    suggestedPattern?: FailurePattern;
+}
+type CreateGroupInput = Omit<IncidentGroup, 'id' | 'count'>;
+type FlowEventType = 'gate-passed' | 'gate-failed' | 'signal-emitted' | 'state-changed' | 'flow-started' | 'flow-ended' | 'error';
+interface FlowEvent {
+    timestamp: string;
+    symbol: string;
+    type: FlowEventType;
+    data?: Record<string, unknown>;
+}
+interface FlowTimeline {
+    incidentId: string;
+    flowId: string;
+    events: FlowEvent[];
+    failure: {
+        at: string;
+        symbol: string;
+        reason: string;
+    };
+}
+interface DayCount {
+    date: string;
+    count: number;
+}
+interface PatternEffectiveness {
+    patternId: string;
+    resolvedCount: number;
+}
+interface PatternRecurrence {
+    patternId: string;
+    recurrenceRate: number;
+}
+interface SymbolIncidentCount {
+    symbol: string;
+    count: number;
+}
+interface SymbolResolutionTime {
+    symbol: string;
+    avgTimeToResolve: number;
+}
+interface SymbolHotspot {
+    symbol: string;
+    incidentRate: number;
+}
+interface SentinelStats {
+    period: {
+        start: string;
+        end: string;
+    };
+    incidents: {
+        total: number;
+        open: number;
+        resolved: number;
+        byEnvironment: Record<string, number>;
+        byDay: DayCount[];
+    };
+    patterns: {
+        total: number;
+        avgConfidence: number;
+        mostEffective: PatternEffectiveness[];
+        leastEffective: PatternRecurrence[];
+    };
+    symbols: {
+        mostIncidents: SymbolIncidentCount[];
+        mostResolved: SymbolResolutionTime[];
+        hotspots: SymbolHotspot[];
+    };
+    resolution: {
+        avgTimeToResolve: number;
+        resolvedWithPattern: number;
+        resolvedManually: number;
+        resolutionRate: number;
+    };
+}
+interface SymbolHealth {
+    incidentCount: number;
+    avgTimeToResolve: number;
+    topPatterns: {
+        patternId: string;
+        count: number;
+    }[];
+}
+interface PatternExport {
+    version: string;
+    exportedAt: string;
+    patterns: FailurePattern[];
+}
+interface BackupExport {
+    version: string;
+    exportedAt: string;
+    incidents: SymbolicIncidentRecord[];
+    patterns: FailurePattern[];
+    groups: IncidentGroup[];
+}
+interface SymbolEnrichment {
+    description?: string;
+    definedIn?: string;
+    references?: string[];
+    referencedBy?: string[];
+}
+interface EnrichedIncident extends SymbolicIncidentRecord {
+    enriched: {
+        symbols: Record<string, SymbolEnrichment>;
+        flowDescription?: string;
+    };
+}
+interface IncidentQueryOptions {
+    limit?: number;
+    offset?: number;
+    status?: IncidentStatus | 'all';
+    environment?: string;
+    symbol?: string;
+    search?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    groupId?: string;
+}
+interface PatternQueryOptions {
+    source?: PatternSource;
+    minConfidence?: number;
+    tags?: string[];
+    includePrivate?: boolean;
+}
+interface ResolutionRecord {
+    id: string;
+    incidentId: string;
+    patternId?: string;
+    commitHash?: string;
+    prUrl?: string;
+    notes?: string;
+    resolvedAt: string;
+    recurred: boolean;
+}
+interface ResolutionQueryOptions {
+    symbol?: string;
+    patternId?: string;
+    limit?: number;
+}
+interface PatternCandidate {
+    incidents: SymbolicIncidentRecord[];
+    suggestedPattern: Partial<FailurePattern>;
+    occurrenceCount: number;
+}
+interface PatternTestResult {
+    wouldMatch: SymbolicIncidentRecord[];
+    matchCount: number;
+    avgScore: number;
+}
+interface SentinelConfig {
+    /** Project name */
+    project: string;
+    /** Default environment for captured incidents */
+    environment?: Environment;
+    /** Service/app name */
+    service?: string;
+    /** App version */
+    version?: string;
+    /** Custom SQLite database path */
+    dbPath?: string;
+    /** Hook called after each incident capture */
+    onCapture?: (incident: SymbolicIncidentRecord) => void;
+}
+interface ComponentContext {
+    /** Component symbol ID (e.g. '#checkout') */
+    id: string;
+    /** Capture an error in this component's context */
+    capture(error: Error, extra?: Record<string, unknown>): string;
+    /** Wrap a function to auto-capture errors in this component's context */
+    wrap<T extends (...args: any[]) => any>(fn: T): T;
+}
+type PracticeResult = 'followed' | 'skipped' | 'partial';
+type PracticeCategory = 'discovery' | 'verification' | 'testing' | 'documentation' | 'collaboration' | 'security';
+interface PracticeEvent {
+    id: string;
+    timestamp: string;
+    habitId: string;
+    habitCategory: PracticeCategory;
+    result: PracticeResult;
+    engineer: string;
+    sessionId: string;
+    loreEntryId?: string;
+    taskDescription?: string;
+    symbolsTouched: string[];
+    filesModified: string[];
+    relatedIncidentId?: string;
+    notes?: string;
+}
+interface PracticeEventInput {
+    habitId: string;
+    habitCategory: PracticeCategory;
+    result: PracticeResult;
+    engineer: string;
+    sessionId: string;
+    loreEntryId?: string;
+    taskDescription?: string;
+    symbolsTouched?: string[];
+    filesModified?: string[];
+    relatedIncidentId?: string;
+    notes?: string;
+}
+interface PracticeEventQuery {
+    habitId?: string;
+    habitCategory?: PracticeCategory;
+    result?: PracticeResult;
+    engineer?: string;
+    sessionId?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * 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;
+    close(): void;
+}
+
+/**
+ * Paradigm Sentinel - Pattern Matching Engine
+ *
+ * Matches incidents against failure patterns using symbolic context,
+ * error text, and missing signals.
+ */
+
+declare class PatternMatcher {
+    private storage;
+    constructor(storage: SentinelStorage);
+    /**
+     * Match an incident against all patterns and return ranked results
+     */
+    match(incident: SymbolicIncidentRecord, config?: Partial<MatcherConfig>): PatternMatch[];
+    /**
+     * Test a pattern against historical incidents
+     */
+    testPattern(pattern: FailurePattern, limit?: number): PatternTestResult;
+    /**
+     * Score how well a pattern matches an incident
+     */
+    private scoreMatch;
+    /**
+     * Match symbols between pattern and incident
+     */
+    private matchSymbols;
+    /**
+     * Match a single symbol value (supports wildcards)
+     */
+    private matchSingleSymbol;
+    /**
+     * Match error text keywords and regex
+     */
+    private matchErrorText;
+    /**
+     * Match missing signals from flow position
+     */
+    private matchMissingSignals;
+    /**
+     * Check if pattern's environment filter matches incident
+     */
+    private matchEnvironment;
+}
+
+/**
+ * Sentinel SDK
+ *
+ * The developer-facing API for capturing errors with symbolic context.
+ * Wraps the core storage and pattern matching engine.
+ *
+ * Usage:
+ *   import { Sentinel } from '@a-company/sentinel';
+ *   const sentinel = new Sentinel({ project: 'my-app' });
+ *   sentinel.capture(new Error('Payment failed'), { component: '#checkout' });
+ */
+
+/**
+ * Flow tracker for monitoring multi-step flows.
+ *
+ * Usage:
+ *   const flow = sentinel.flow('$checkout-flow');
+ *   flow.expect('!payment-authorized', '!order-created');
+ *   flow.gate('^authenticated', true);
+ *   flow.signal('!payment-authorized');
+ *   flow.complete();
+ */
+declare class FlowTracker {
+    private flowId;
+    private sentinel;
+    private actual;
+    private expected;
+    private completed;
+    constructor(flowId: string, sentinel: Sentinel);
+    /** Declare which signals/gates are expected in this flow */
+    expect(...symbols: string[]): this;
+    /** Record a generic step in the flow */
+    step(symbol: string): this;
+    /** Record a gate check result */
+    gate(id: string, passed: boolean): this;
+    /** Record a signal emission */
+    signal(id: string, _data?: object): this;
+    /** Mark the flow as successfully completed */
+    complete(): void;
+    /** Capture an error with full flow position context */
+    fail(error: Error): void;
+}
+/**
+ * The main Sentinel SDK class.
+ *
+ * Usage:
+ *   const sentinel = new Sentinel({ project: 'my-app', environment: 'production' });
+ *
+ *   // Capture errors with symbolic context
+ *   sentinel.capture(error, { component: '#checkout', gate: '^payment-validated' });
+ *
+ *   // Component context for scoped captures
+ *   const ctx = sentinel.component('#checkout');
+ *   ctx.capture(error);
+ *
+ *   // Flow tracking
+ *   const flow = sentinel.flow('$checkout-flow');
+ *   flow.gate('^authenticated', true);
+ *   flow.signal('!payment-authorized');
+ *   flow.complete();
+ */
+declare class Sentinel {
+    private storage;
+    private matcher;
+    private config;
+    private ready;
+    private readyPromise;
+    private seeded;
+    constructor(config: SentinelConfig);
+    /** Explicitly initialize storage. Optional — auto-called on first capture. */
+    init(): Promise<void>;
+    private doInit;
+    private ensureReady;
+    /**
+     * Create a component context for scoped error capture.
+     *
+     * @param id - Component symbol (e.g. '#checkout' or 'checkout')
+     * @returns ComponentContext with capture() and wrap() methods
+     */
+    component(id: string): ComponentContext;
+    /**
+     * Record a gate check result.
+     * If the gate fails, auto-captures an incident.
+     *
+     * @param id - Gate symbol (e.g. '^authenticated' or 'authenticated')
+     * @param passed - Whether the gate passed
+     */
+    gate(id: string, passed: boolean): void;
+    /**
+     * Record a signal emission. Primarily for flow tracking context.
+     *
+     * @param id - Signal symbol (e.g. '!payment-authorized' or 'payment-authorized')
+     */
+    signal(id: string, _data?: object): void;
+    /**
+     * Create a flow tracker for monitoring multi-step operations.
+     *
+     * @param id - Flow symbol (e.g. '$checkout-flow' or 'checkout-flow')
+     * @returns FlowTracker instance
+     */
+    flow(id: string): FlowTracker;
+    /**
+     * Capture an error with symbolic context.
+     *
+     * @param error - The error to capture
+     * @param context - Symbolic context (component, gate, flow, signal)
+     * @param flowPosition - Optional flow position data
+     * @returns Incident ID (e.g. 'INC-001')
+     */
+    capture(error: Error, context?: Partial<SymbolicContext>, flowPosition?: FlowPosition): string;
+    /**
+     * Get pattern matches for a captured incident.
+     *
+     * @param incidentId - The incident ID to match
+     * @returns Array of pattern matches sorted by confidence
+     */
+    match(incidentId: string): PatternMatch[];
+    /**
+     * Create Express error-handling middleware.
+     *
+     * Usage:
+     *   app.use(sentinel.express());
+     */
+    express(): any;
+    /** Close the database connection. Call when shutting down. */
+    close(): void;
+    /** Get the underlying storage instance (for advanced usage). */
+    getStorage(): SentinelStorage;
+    /** Get the underlying pattern matcher (for advanced usage). */
+    getMatcher(): PatternMatcher;
+}
+
+export { type SymbolResolutionTime as $, type PatternRecurrence as A, type BackupExport as B, type ComponentContext as C, type DayCount as D, type EnrichedIncident as E, type FlowTimeline as F, type PatternResolution as G, type PatternSource as H, type IncidentGroup as I, type PatternSymbolCriteria as J, type PatternTestResult as K, type PracticeCategory as L, type MatchedCriteria as M, type PracticeEvent as N, type PracticeEventInput as O, type PatternCandidate as P, type PracticeEventQuery as Q, type PracticeResult as R, SentinelStorage as S, type Resolution as T, type ResolutionQueryOptions as U, type ResolutionRecord as V, type ResolutionStrategy as W, Sentinel as X, type SentinelConfig as Y, type SymbolHotspot as Z, type SymbolIncidentCount as _, type SymbolicIncidentRecord as a, type SymbolicContext as a0, type SentinelStats as b, type SymbolHealth as c, type SymbolEnrichment as d, type FailurePattern as e, type PatternExport as f, type CreateGroupInput as g, type CreateIncidentInput as h, type CreatePatternInput as i, type Environment as j, type ErrorDetails as k, type FlowEvent as l, type FlowEventType as m, type FlowPosition as n, FlowTracker as o, type IncidentNote as p, type IncidentQueryOptions as q, type IncidentStatus as r, type MatcherConfig as s, type PatternConfidence as t, type PatternCriteria as u, type PatternEffectiveness as v, type PatternMatch as w, PatternMatcher as x, type PatternPriority as y, type PatternQueryOptions as z };