reflectt-node 0.1.0

package/dist/activationEvents.js

@@ -0,0 +1,378 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) Reflectt AI
+/**
+ * Activation Funnel Events — 6 lifecycle hooks for measuring
+ * signup-to-value conversion at launch.
+ *
+ * Events:
+ *   1. signup_completed     — User account created and verified
+ *   2. workspace_ready      — Org + team + first host connected
+ *   3. first_task_started   — First task moved to "doing"
+ *   4. first_task_completed — First task moved to "done"
+ *   5. first_team_message_sent — First chat message sent by a human user
+ *   6. day2_return_action   — Any meaningful action ≥24h after signup
+ *
+ * Each event is recorded once per userId (idempotent).
+ * Events are persisted to a JSONL audit file and queryable via
+ * GET /activation/funnel.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const DATA_DIR = process.env.REFLECTT_DATA_DIR || path.join(process.cwd(), 'data');
+const FUNNEL_FILE = path.join(DATA_DIR, 'activation-funnel.jsonl');
+/* ─── In-memory state ─── */
+/** userId → { eventType → timestamp } */
+const userFunnels = new Map();
+/** Ordered event log (also persisted) */
+const eventLog = [];
+const MAX_LOG_SIZE = 10_000;
+const FUNNEL_ORDER = [
+    'signup_completed',
+    'host_preflight_passed',
+    // Note: host_preflight_failed is tracked in the event log but is NOT a
+    // forward funnel step — failure doesn't represent onboarding progress.
+    'workspace_ready',
+    'first_task_started',
+    'first_task_completed',
+    'first_team_message_sent',
+    'day2_return_action',
+];
+/* ─── Core API ─── */
+/**
+ * Emit an activation event. Idempotent per (userId, type).
+ * Returns true if this was the first time the event fired for this user.
+ */
+export async function emitActivationEvent(type, userId, metadata) {
+    if (!userId)
+        return false;
+    let userMap = userFunnels.get(userId);
+    if (!userMap) {
+        userMap = new Map();
+        userFunnels.set(userId, userMap);
+    }
+    // Idempotent: skip if already recorded
+    if (userMap.has(type))
+        return false;
+    const timestamp = Date.now();
+    userMap.set(type, timestamp);
+    const event = { type, userId, timestamp, metadata };
+    eventLog.push(event);
+    if (eventLog.length > MAX_LOG_SIZE) {
+        eventLog.splice(0, eventLog.length - MAX_LOG_SIZE);
+    }
+    // Persist (best-effort)
+    try {
+        await fs.mkdir(DATA_DIR, { recursive: true });
+        await fs.appendFile(FUNNEL_FILE, JSON.stringify(event) + '\n', 'utf-8');
+    }
+    catch (err) {
+        console.error('[ActivationFunnel] Failed to persist event:', err);
+    }
+    return true;
+}
+/**
+ * Get funnel state for a specific user.
+ */
+export function getUserFunnelState(userId) {
+    const userMap = userFunnels.get(userId);
+    const events = {
+        signup_completed: null,
+        host_preflight_passed: null,
+        host_preflight_failed: null,
+        workspace_ready: null,
+        first_task_started: null,
+        first_task_completed: null,
+        first_team_message_sent: null,
+        day2_return_action: null,
+    };
+    let currentStep = 0;
+    if (userMap) {
+        for (const type of FUNNEL_ORDER) {
+            const ts = userMap.get(type);
+            if (ts !== undefined) {
+                events[type] = ts;
+                currentStep++;
+            }
+        }
+        // Populate tracked-but-not-funnel events (e.g. host_preflight_failed)
+        for (const [type, ts] of userMap) {
+            if (!FUNNEL_ORDER.includes(type) && events[type] === null) {
+                events[type] = ts;
+            }
+        }
+    }
+    const allDone = currentStep === FUNNEL_ORDER.length;
+    const completedAt = allDone
+        ? Math.max(...Object.values(events).filter((v) => v !== null))
+        : null;
+    return { userId, events, currentStep, completedAt };
+}
+/**
+ * Get funnel summary across all users.
+ */
+export function getFunnelSummary() {
+    const stepCounts = {
+        signup_completed: 0,
+        host_preflight_passed: 0,
+        host_preflight_failed: 0,
+        workspace_ready: 0,
+        first_task_started: 0,
+        first_task_completed: 0,
+        first_team_message_sent: 0,
+        day2_return_action: 0,
+    };
+    const funnelByUser = [];
+    let completedUsers = 0;
+    for (const userId of userFunnels.keys()) {
+        const state = getUserFunnelState(userId);
+        funnelByUser.push(state);
+        for (const type of FUNNEL_ORDER) {
+            if (state.events[type] !== null) {
+                stepCounts[type]++;
+            }
+        }
+        if (state.completedAt !== null)
+            completedUsers++;
+    }
+    return {
+        totalUsers: userFunnels.size,
+        stepCounts,
+        completedUsers,
+        funnelByUser,
+    };
+}
+/**
+ * Check if a user has completed a specific event.
+ */
+export function hasCompletedEvent(userId, type) {
+    return userFunnels.get(userId)?.has(type) ?? false;
+}
+/**
+ * Get the signup timestamp for a user (for day2 calculation).
+ */
+export function getSignupTimestamp(userId) {
+    return userFunnels.get(userId)?.get('signup_completed') ?? null;
+}
+/**
+ * Check if ≥24h have passed since signup (for day2_return_action eligibility).
+ */
+export function isDay2Eligible(userId) {
+    const signupTs = getSignupTimestamp(userId);
+    if (!signupTs)
+        return false;
+    return (Date.now() - signupTs) >= 24 * 60 * 60 * 1000;
+}
+/**
+ * Load persisted funnel events from disk on startup.
+ */
+export async function loadActivationFunnel() {
+    try {
+        const data = await fs.readFile(FUNNEL_FILE, 'utf-8');
+        const lines = data.split('\n').filter(l => l.trim());
+        let loaded = 0;
+        for (const line of lines) {
+            try {
+                const event = JSON.parse(line);
+                if (!event.type || !event.userId || !event.timestamp)
+                    continue;
+                let userMap = userFunnels.get(event.userId);
+                if (!userMap) {
+                    userMap = new Map();
+                    userFunnels.set(event.userId, userMap);
+                }
+                // Only keep the first occurrence
+                if (!userMap.has(event.type)) {
+                    userMap.set(event.type, event.timestamp);
+                }
+                eventLog.push(event);
+                loaded++;
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        if (eventLog.length > MAX_LOG_SIZE) {
+            eventLog.splice(0, eventLog.length - MAX_LOG_SIZE);
+        }
+        return loaded;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return 0;
+        console.error('[ActivationFunnel] Failed to load funnel data:', err);
+        return 0;
+    }
+}
+/**
+ * Get step-by-step conversion funnel with rates and timing.
+ */
+export function getConversionFunnel() {
+    const conversions = [];
+    let prevReached = userFunnels.size; // total users = denominator for first step
+    for (let i = 0; i < FUNNEL_ORDER.length; i++) {
+        const step = FUNNEL_ORDER[i];
+        let reached = 0;
+        for (const userMap of userFunnels.values()) {
+            if (userMap.has(step))
+                reached++;
+        }
+        // Compute median time from previous step
+        let medianTimeMs = null;
+        if (i > 0) {
+            const prevStep = FUNNEL_ORDER[i - 1];
+            const deltas = [];
+            for (const userMap of userFunnels.values()) {
+                const prevTs = userMap.get(prevStep);
+                const thisTs = userMap.get(step);
+                if (prevTs !== undefined && thisTs !== undefined) {
+                    deltas.push(thisTs - prevTs);
+                }
+            }
+            if (deltas.length > 0) {
+                deltas.sort((a, b) => a - b);
+                medianTimeMs = deltas[Math.floor(deltas.length / 2)];
+            }
+        }
+        conversions.push({
+            step,
+            reached,
+            conversionRate: prevReached > 0 ? reached / prevReached : 0,
+            medianTimeMs,
+        });
+        prevReached = reached;
+    }
+    return conversions;
+}
+/**
+ * Get failure-reason distribution per step.
+ * Looks at event metadata for `failed_checks`, `first_blocker`, `error`, etc.
+ */
+export function getFailureDistribution() {
+    const distribution = [];
+    for (let i = 0; i < FUNNEL_ORDER.length; i++) {
+        const step = FUNNEL_ORDER[i];
+        const prevStep = i > 0 ? FUNNEL_ORDER[i - 1] : null;
+        // Count users who reached prev step but not this one
+        let droppedCount = 0;
+        const reasonCounts = new Map();
+        for (const [userId, userMap] of userFunnels.entries()) {
+            const reachedPrev = prevStep === null || userMap.has(prevStep);
+            const reachedThis = userMap.has(step);
+            if (reachedPrev && !reachedThis) {
+                droppedCount++;
+                // Check if there's a failure event with metadata
+                // For preflight: host_preflight_failed has failed_checks/first_blocker
+                const failEvent = step === 'host_preflight_passed'
+                    ? eventLog.find(e => e.userId === userId && e.type === 'host_preflight_failed')
+                    : null;
+                if (failEvent?.metadata) {
+                    const meta = failEvent.metadata;
+                    if (Array.isArray(meta.failed_checks)) {
+                        for (const check of meta.failed_checks) {
+                            reasonCounts.set(check, (reasonCounts.get(check) || 0) + 1);
+                        }
+                    }
+                    else if (meta.first_blocker) {
+                        const reason = String(meta.first_blocker);
+                        reasonCounts.set(reason, (reasonCounts.get(reason) || 0) + 1);
+                    }
+                    else if (meta.error) {
+                        const reason = String(meta.error);
+                        reasonCounts.set(reason, (reasonCounts.get(reason) || 0) + 1);
+                    }
+                }
+                // Generic: check for any failure metadata on events at this step
+                const stepFailEvents = eventLog.filter(e => e.userId === userId && e.metadata?.failedAt === step);
+                for (const fe of stepFailEvents) {
+                    const reason = String(fe.metadata?.reason || 'unknown');
+                    reasonCounts.set(reason, (reasonCounts.get(reason) || 0) + 1);
+                }
+            }
+        }
+        const reasons = Array.from(reasonCounts.entries())
+            .map(([reason, count]) => ({ reason, count }))
+            .sort((a, b) => b.count - a.count);
+        // Add "unspecified" for drops without metadata
+        const specifiedDrops = reasons.reduce((sum, r) => sum + r.count, 0);
+        if (droppedCount > specifiedDrops) {
+            reasons.push({ reason: 'unspecified', count: droppedCount - specifiedDrops });
+        }
+        distribution.push({ step, droppedCount, reasons });
+    }
+    return distribution;
+}
+/**
+ * Get weekly trend snapshots for planning.
+ * Groups events by ISO week (Monday–Sunday).
+ */
+export function getWeeklyTrends(weekCount = 12) {
+    const now = Date.now();
+    const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
+    // Calculate week boundaries going back `weekCount` weeks
+    const trends = [];
+    // Find Monday of the current week as anchor
+    const anchor = new Date(now);
+    const anchorDay = anchor.getUTCDay();
+    const anchorMondayOffset = anchorDay === 0 ? -6 : 1 - anchorDay;
+    anchor.setUTCDate(anchor.getUTCDate() + anchorMondayOffset);
+    anchor.setUTCHours(0, 0, 0, 0);
+    const currentMondayTs = anchor.getTime();
+    for (let w = weekCount - 1; w >= 0; w--) {
+        const mondayTs = currentMondayTs - w * MS_PER_WEEK;
+        const sundayTs = mondayTs + MS_PER_WEEK - 1;
+        const stepCounts = {
+            signup_completed: 0,
+            host_preflight_passed: 0,
+            host_preflight_failed: 0,
+            workspace_ready: 0,
+            first_task_started: 0,
+            first_task_completed: 0,
+            first_team_message_sent: 0,
+            day2_return_action: 0,
+        };
+        let newUsers = 0;
+        let completedUsers = 0;
+        // Count events in this week window
+        for (const event of eventLog) {
+            if (event.timestamp >= mondayTs && event.timestamp <= sundayTs) {
+                if (event.type in stepCounts) {
+                    stepCounts[event.type]++;
+                }
+                if (event.type === 'signup_completed')
+                    newUsers++;
+                if (event.type === 'day2_return_action')
+                    completedUsers++;
+            }
+        }
+        trends.push({
+            weekStart: new Date(mondayTs).toISOString().slice(0, 10),
+            weekEnd: new Date(sundayTs).toISOString().slice(0, 10),
+            newUsers,
+            completedUsers,
+            stepCounts,
+            conversionRate: newUsers > 0 ? completedUsers / newUsers : 0,
+        });
+    }
+    return trends;
+}
+/**
+ * Full onboarding telemetry dashboard snapshot.
+ * Combines funnel, failure distribution, and trends.
+ */
+export function getOnboardingDashboard(opts) {
+    return {
+        timestamp: Date.now(),
+        funnel: getConversionFunnel(),
+        failures: getFailureDistribution(),
+        trends: getWeeklyTrends(opts?.weeks || 12),
+        summary: getFunnelSummary(),
+    };
+}
+/**
+ * Reset funnel state (for testing).
+ */
+export function resetActivationFunnel() {
+    userFunnels.clear();
+    eventLog.length = 0;
+}
+//# sourceMappingURL=activationEvents.js.map

package/dist/activationEvents.js.map

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

package/dist/activity-signal.d.ts

@@ -0,0 +1,30 @@
+export type ActivitySource = 'status_comment' | 'state_transition' | 'task_created' | 'none';
+export interface ActivitySignal {
+    /** The effective timestamp used for enforcement decisions */
+    effectiveActivityTs: number;
+    /** Which source produced the winning timestamp */
+    source: ActivitySource;
+    /** Individual signal timestamps for debugging */
+    signals: {
+        lastCommentAt: number | null;
+        lastStateTransitionAt: number | null;
+        taskCreatedAt: number;
+    };
+}
+/**
+ * Compute the effective activity signal for a task.
+ *
+ * @param taskId - Task ID
+ * @param agent - Optional: restrict comment lookups to this agent
+ * @param taskCreatedAt - Fallback timestamp (from task record)
+ * @returns ActivitySignal with effective timestamp and source
+ */
+export declare function getEffectiveActivity(taskId: string, agent?: string | null, taskCreatedAt?: number): ActivitySignal;
+/**
+ * Format an activity signal for inclusion in warning messages.
+ *
+ * Example output:
+ *   "last activity: 47m ago (status_comment at 2025-01-15 14:23 UTC), threshold: 90m"
+ */
+export declare function formatActivityWarning(signal: ActivitySignal, thresholdMin: number, now?: number): string;
+//# sourceMappingURL=activity-signal.d.ts.map

package/dist/activity-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-signal.d.ts","sourceRoot":"","sources":["../src/activity-signal.ts"],"names":[],"mappings":"AAuBA,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,MAAM,CAAA;AAEV,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,mBAAmB,EAAE,MAAM,CAAA;IAC3B,kDAAkD;IAClD,MAAM,EAAE,cAAc,CAAA;IACtB,iDAAiD;IACjD,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;QAC5B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAA;QACpC,aAAa,EAAE,MAAM,CAAA;KACtB,CAAA;CACF;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,cAAc,CA6DhB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAOR"}

package/dist/activity-signal.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) Reflectt AI
+/**
+ * Activity Signal — canonical "last real activity" for enforcement decisions.
+ *
+ * Problem: task.updatedAt is brittle — it's bumped by metadata edits, reviewer
+ * assignment, and other non-activity changes. Enforcement keying off updatedAt
+ * produces false stale warnings.
+ *
+ * Solution: effective_activity_ts = max(
+ *   last_status_comment_at,   — most recent task comment by assigned agent
+ *   last_state_transition_at, — most recent status change in task_history
+ *   task_created_at,          — fallback for brand-new tasks
+ * )
+ *
+ * Each signal source is tracked so warnings can report WHY enforcement fired.
+ */
+import { getDb } from './db.js';
+// ── Core function ──
+/**
+ * Compute the effective activity signal for a task.
+ *
+ * @param taskId - Task ID
+ * @param agent - Optional: restrict comment lookups to this agent
+ * @param taskCreatedAt - Fallback timestamp (from task record)
+ * @returns ActivitySignal with effective timestamp and source
+ */
+export function getEffectiveActivity(taskId, agent, taskCreatedAt) {
+    const db = getDb();
+    const now = Date.now();
+    if (taskCreatedAt === undefined) {
+        // Warn: callers should always pass task.createdAt to avoid masking staleness
+        console.warn(`[activity-signal] taskCreatedAt not provided for task ${taskId} — falling back to now (may mask staleness)`);
+    }
+    const created = taskCreatedAt ?? now;
+    // 1. Last comment by the agent (or any author)
+    let lastCommentAt = null;
+    try {
+        const commentQuery = agent
+            ? db.prepare('SELECT MAX(timestamp) as latest FROM task_comments WHERE task_id = ? AND author = ? AND (suppressed IS NULL OR suppressed = 0)').get(taskId, agent)
+            : db.prepare('SELECT MAX(timestamp) as latest FROM task_comments WHERE task_id = ? AND (suppressed IS NULL OR suppressed = 0)').get(taskId);
+        lastCommentAt = commentQuery?.latest ?? null;
+    }
+    catch (err) {
+        // DB not available — fall through to createdAt (may revert to updatedAt-like behavior)
+        console.warn(`[activity-signal] comment query failed for task ${taskId}, falling back:`, err.message);
+    }
+    // 2. Last state transition from task_history
+    let lastStateTransitionAt = null;
+    try {
+        const historyRow = db.prepare('SELECT MAX(timestamp) as latest FROM task_history WHERE task_id = ?').get(taskId);
+        lastStateTransitionAt = historyRow?.latest ?? null;
+    }
+    catch (err) {
+        // DB not available — fall through to createdAt
+        console.warn(`[activity-signal] history query failed for task ${taskId}, falling back:`, err.message);
+    }
+    // 3. Determine winner (monotonic: highest timestamp wins)
+    const candidates = [];
+    if (lastCommentAt !== null && lastCommentAt > 0) {
+        candidates.push({ ts: lastCommentAt, source: 'status_comment' });
+    }
+    if (lastStateTransitionAt !== null && lastStateTransitionAt > 0) {
+        candidates.push({ ts: lastStateTransitionAt, source: 'state_transition' });
+    }
+    candidates.push({ ts: created, source: 'task_created' });
+    // Sort descending — highest timestamp wins (monotonic guard)
+    candidates.sort((a, b) => b.ts - a.ts);
+    const winner = candidates[0];
+    return {
+        effectiveActivityTs: winner.ts,
+        source: winner.source,
+        signals: {
+            lastCommentAt,
+            lastStateTransitionAt,
+            taskCreatedAt: created,
+        },
+    };
+}
+/**
+ * Format an activity signal for inclusion in warning messages.
+ *
+ * Example output:
+ *   "last activity: 47m ago (status_comment at 2025-01-15 14:23 UTC), threshold: 90m"
+ */
+export function formatActivityWarning(signal, thresholdMin, now) {
+    const ts = now || Date.now();
+    const ageMin = Math.max(0, Math.floor((ts - signal.effectiveActivityTs) / 60_000));
+    const sourceLabel = signal.source.replace(/_/g, ' ');
+    const timeStr = new Date(signal.effectiveActivityTs).toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+    return `last activity: ${ageMin}m ago (${sourceLabel} at ${timeStr}), threshold: ${thresholdMin}m`;
+}
+//# sourceMappingURL=activity-signal.js.map

package/dist/activity-signal.js.map

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

package/dist/alert-integrity.d.ts

@@ -0,0 +1,100 @@
+export interface AlertPreflightInput {
+    /** Task the alert is about */
+    taskId: string;
+    /** Type of alert being sent */
+    alertType: 'sla_warning' | 'sla_breach' | 'stale_task' | 'requeue' | 'idle_nudge' | 'watchdog' | 'escalation' | 'mention_rescue' | 'generic';
+    /** The alert content (for dedup hashing) */
+    content: string;
+    /** Who triggered the alert */
+    from: string;
+    /** Expected task state when alert was generated */
+    expectedState?: {
+        status?: string;
+        assignee?: string;
+        reviewer?: string;
+    };
+}
+export interface AlertPreflightResult {
+    /** Whether the alert should be published */
+    allowed: boolean;
+    /** Why the alert was allowed or suppressed */
+    reason: string;
+    /** Detailed reason code for metrics */
+    reasonCode: 'allowed' | 'task_not_found' | 'status_changed' | 'assignee_changed' | 'recent_activity' | 'duplicate' | 'task_done' | 'canary_allowed';
+    /** Live task state at preflight time */
+    liveState?: {
+        status: string;
+        assignee: string;
+        reviewer: string;
+        lastCommentTs: number | null;
+        stateHash: string;
+    };
+    /** Preflight latency in ms */
+    latencyMs: number;
+}
+export interface AlertIntegrityConfig {
+    /** Enable preflight checks (default: true) */
+    enabled: boolean;
+    /** Canary mode — log but don't suppress (default: true) */
+    canaryMode: boolean;
+    /** Recent activity window — suppress alerts if task was commented on within this window */
+    recentActivityWindowMs: number;
+    /** Idempotent dedup window — suppress identical alerts within this window */
+    dedupWindowMs: number;
+    /** Alert types that bypass preflight (always send) */
+    bypassTypes: string[];
+    /** Maximum dedup cache entries */
+    maxDedupEntries: number;
+}
+export interface AlertIntegrityStats {
+    totalChecked: number;
+    totalAllowed: number;
+    totalSuppressed: number;
+    suppressionsByReason: Record<string, number>;
+    canaryWouldSuppress: number;
+    avgLatencyMs: number;
+    p95LatencyMs: number;
+}
+export declare class AlertIntegrityGuard {
+    private config;
+    private dedupCache;
+    private auditLog;
+    private latencies;
+    private stats;
+    constructor(config?: Partial<AlertIntegrityConfig>);
+    /**
+     * Run preflight reconciliation for a task-scoped alert.
+     * Returns whether the alert should be published.
+     */
+    preflight(input: AlertPreflightInput): AlertPreflightResult;
+    private buildLiveState;
+    private computeStateHash;
+    private computeIdempotentKey;
+    private maybeCanary;
+    private recordResult;
+    private updateLatencyStats;
+    private pruneDedupCache;
+    getStats(): AlertIntegrityStats;
+    getAuditLog(options?: {
+        limit?: number;
+        since?: number;
+        taskId?: string;
+    }): typeof this.auditLog;
+    /**
+     * Get rollback signals for canary evaluation.
+     */
+    getRollbackSignals(): {
+        missedTruePositives: number;
+        p95LatencyMs: number;
+        criticalAlertErrors: number;
+        rollbackTriggered: boolean;
+    };
+    getConfig(): Readonly<AlertIntegrityConfig>;
+    updateConfig(updates: Partial<AlertIntegrityConfig>): void;
+    /** Exit canary mode — start enforcing suppression */
+    activateEnforcement(): void;
+    /** Reset stats (for testing) */
+    resetStats(): void;
+}
+export declare const alertIntegrityGuard: AlertIntegrityGuard;
+//# sourceMappingURL=alert-integrity.d.ts.map

package/dist/alert-integrity.d.ts.map

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