@skillsmith/core 0.5.5 → 0.5.6

package/dist/utils/logger.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Logger Utility with Audit Support (SMI-728)
+ *
+ * Enhanced logger with structured logging, audit trails, and security events.
+ * Provides environment-aware logging with different verbosity levels and
+ * support for audit event tracking.
+ */
+/**
+ * Log severity levels
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    AUDIT = 4,
+    SECURITY = 5
+}
+/**
+ * Audit event types
+ */
+export type AuditEventType = 'skill.install' | 'skill.uninstall' | 'skill.fetch' | 'skill.scan' | 'adapter.request' | 'adapter.error' | 'cache.hit' | 'cache.miss' | 'security.violation';
+/**
+ * Security event types
+ */
+export type SecurityEventType = 'ssrf.blocked' | 'path_traversal.blocked' | 'validation.failed' | 'rate_limit.exceeded' | 'malware.detected' | 'suspicious.pattern';
+/**
+ * Audit event structure
+ */
+export interface AuditEvent {
+    /** Type of audit event */
+    eventType: AuditEventType;
+    /** When the event occurred */
+    timestamp: string;
+    /** Who performed the action (user, system, adapter) */
+    actor: string;
+    /** Resource being accessed (URL, path, skill_id) */
+    resource: string;
+    /** Action being performed (fetch, read, install, scan) */
+    action: string;
+    /** Result of the action (success, blocked, error) */
+    result: 'success' | 'blocked' | 'error';
+    /** Additional context as key-value pairs */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Security event structure
+ */
+export interface SecurityEvent {
+    /** Type of security event */
+    eventType: SecurityEventType;
+    /** When the event occurred */
+    timestamp: string;
+    /** Severity level (low, medium, high, critical) */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /** Resource being protected */
+    resource: string;
+    /** Action that was blocked/detected */
+    action: string;
+    /** Details about the security event */
+    details: string;
+    /** Additional context */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+    level: LogLevel;
+    timestamp: string;
+    namespace?: string;
+    message: string;
+    context?: Record<string, unknown>;
+    error?: Error;
+}
+/**
+ * Log aggregator interface for future persistence
+ */
+export interface LogAggregator {
+    /** Add a log entry to the aggregator */
+    add(entry: LogEntry): void;
+    /** Add an audit event */
+    addAudit(event: AuditEvent): void;
+    /** Add a security event */
+    addSecurity(event: SecurityEvent): void;
+    /** Flush logs to persistence layer */
+    flush(): Promise<void>;
+    /** Get all logs */
+    getLogs(): LogEntry[];
+    /** Get all audit events */
+    getAuditEvents(): AuditEvent[];
+    /** Get all security events */
+    getSecurityEvents(): SecurityEvent[];
+}
+/**
+ * Logger interface with audit support
+ */
+export interface Logger {
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, error?: Error, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    auditLog: (event: AuditEvent) => void;
+    securityLog: (event: SecurityEvent) => void;
+}
+/**
+ * Set the global log aggregator
+ */
+export declare function setLogAggregator(aggregator: LogAggregator): void;
+/**
+ * Get the global log aggregator
+ */
+export declare function getLogAggregator(): LogAggregator;
+/**
+ * Default logger instance
+ *
+ * Environment variables:
+ * - NODE_ENV=test: Suppress warn/info/debug output
+ * - DEBUG=true: Enable info and debug output
+ * - LOG_FORMAT=json: Output logs in JSON format
+ * - LOG_LEVEL=0-5: Minimum log level to output
+ * - AUDIT_LOG=true: Enable audit log output
+ *
+ * @example
+ * ```typescript
+ * logger.info('Processing skill', { skillId: 'foo' })
+ * logger.error('Failed to fetch', new Error('Network error'))
+ * logger.auditLog({
+ *   eventType: 'skill.install',
+ *   timestamp: new Date().toISOString(),
+ *   actor: 'user',
+ *   resource: 'skill-id',
+ *   action: 'install',
+ *   result: 'success'
+ * })
+ * ```
+ */
+export declare const logger: Logger;
+/**
+ * Create a namespaced logger
+ *
+ * @param namespace - The namespace prefix for log messages
+ * @returns A Logger instance with namespaced messages
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('GitLabAdapter')
+ * log.warn('Rate limit exceeded', { remaining: 0 })
+ * log.auditLog({
+ *   eventType: 'adapter.request',
+ *   timestamp: new Date().toISOString(),
+ *   actor: 'GitLabAdapter',
+ *   resource: 'https://gitlab.com/api/v4/projects',
+ *   action: 'fetch',
+ *   result: 'success'
+ * })
+ * ```
+ */
+export declare function createLogger(namespace: string): Logger;
+/**
+ * No-op logger for testing or silent operation
+ */
+export declare const silentLogger: Logger;
+/**
+ * Helper to create audit events with current timestamp
+ */
+export declare function createAuditEvent(eventType: AuditEventType, actor: string, resource: string, action: string, result: 'success' | 'blocked' | 'error', metadata?: Record<string, unknown>): AuditEvent;
+/**
+ * Helper to create security events with current timestamp
+ */
+export declare function createSecurityEvent(eventType: SecurityEventType, severity: 'low' | 'medium' | 'high' | 'critical', resource: string, action: string, details: string, metadata?: Record<string, unknown>): SecurityEvent;
+//# sourceMappingURL=logger.d.ts.map

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

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

package/dist/utils/logger.js

@@ -0,0 +1,291 @@
+/**
+ * Logger Utility with Audit Support (SMI-728)
+ *
+ * Enhanced logger with structured logging, audit trails, and security events.
+ * Provides environment-aware logging with different verbosity levels and
+ * support for audit event tracking.
+ */
+/**
+ * Log severity levels
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["AUDIT"] = 4] = "AUDIT";
+    LogLevel[LogLevel["SECURITY"] = 5] = "SECURITY";
+})(LogLevel || (LogLevel = {}));
+/**
+ * In-memory log aggregator
+ */
+class MemoryLogAggregator {
+    logs = [];
+    auditEvents = [];
+    securityEvents = [];
+    maxSize;
+    constructor(maxSize = 10000) {
+        this.maxSize = maxSize;
+    }
+    add(entry) {
+        this.logs.push(entry);
+        if (this.logs.length > this.maxSize) {
+            this.logs.shift();
+        }
+    }
+    addAudit(event) {
+        this.auditEvents.push(event);
+        if (this.auditEvents.length > this.maxSize) {
+            this.auditEvents.shift();
+        }
+    }
+    addSecurity(event) {
+        this.securityEvents.push(event);
+        if (this.securityEvents.length > this.maxSize) {
+            this.securityEvents.shift();
+        }
+    }
+    async flush() {
+        // Future: Persist to database
+        // For now, this is a no-op
+    }
+    getLogs() {
+        return [...this.logs];
+    }
+    getAuditEvents() {
+        return [...this.auditEvents];
+    }
+    getSecurityEvents() {
+        return [...this.securityEvents];
+    }
+    clear() {
+        this.logs = [];
+        this.auditEvents = [];
+        this.securityEvents = [];
+    }
+}
+/**
+ * Global log aggregator instance
+ */
+let globalAggregator = new MemoryLogAggregator();
+/**
+ * Set the global log aggregator
+ */
+export function setLogAggregator(aggregator) {
+    globalAggregator = aggregator;
+}
+/**
+ * Get the global log aggregator
+ */
+export function getLogAggregator() {
+    return globalAggregator;
+}
+/**
+ * Format log entry for output
+ */
+function formatLogEntry(entry, useJson) {
+    if (useJson) {
+        return JSON.stringify({
+            level: LogLevel[entry.level],
+            timestamp: entry.timestamp,
+            namespace: entry.namespace,
+            message: entry.message,
+            context: entry.context,
+            error: entry.error
+                ? {
+                    message: entry.error.message,
+                    stack: entry.error.stack,
+                }
+                : undefined,
+        });
+    }
+    const prefix = entry.namespace ? `[skillsmith:${entry.namespace}]` : '[skillsmith]';
+    const contextStr = entry.context ? ` ${JSON.stringify(entry.context)}` : '';
+    return `${prefix} ${entry.message}${contextStr}`;
+}
+/**
+ * Format audit event for output
+ */
+function formatAuditEvent(event, useJson) {
+    if (useJson) {
+        return JSON.stringify(event);
+    }
+    const metaStr = event.metadata ? ` ${JSON.stringify(event.metadata)}` : '';
+    return `[AUDIT] ${event.eventType} | ${event.actor} -> ${event.action} on ${event.resource} = ${event.result}${metaStr}`;
+}
+/**
+ * Format security event for output
+ */
+function formatSecurityEvent(event, useJson) {
+    if (useJson) {
+        return JSON.stringify(event);
+    }
+    const metaStr = event.metadata ? ` ${JSON.stringify(event.metadata)}` : '';
+    return `[SECURITY:${event.severity.toUpperCase()}] ${event.eventType} | ${event.action} on ${event.resource} - ${event.details}${metaStr}`;
+}
+/**
+ * Create a logger instance
+ */
+function createLoggerInstance(namespace) {
+    const useJson = process.env.LOG_FORMAT === 'json';
+    const minLevel = process.env.LOG_LEVEL ? parseInt(process.env.LOG_LEVEL, 10) : LogLevel.WARN;
+    const shouldLog = (level) => {
+        // In test mode, suppress WARN to keep test output clean
+        // (but don't suppress INFO/DEBUG if DEBUG is enabled, or ERROR which is always shown)
+        if (process.env.NODE_ENV === 'test' && level === LogLevel.WARN) {
+            return false;
+        }
+        // DEBUG flag enables info and debug output
+        if (level === LogLevel.DEBUG || level === LogLevel.INFO) {
+            return !!process.env.DEBUG;
+        }
+        return level >= minLevel;
+    };
+    const createLogEntry = (level, message, context, error) => ({
+        level,
+        timestamp: new Date().toISOString(),
+        namespace,
+        message,
+        context,
+        error,
+    });
+    return {
+        warn: (message, context) => {
+            const entry = createLogEntry(LogLevel.WARN, message, context);
+            if (shouldLog(LogLevel.WARN)) {
+                console.warn(formatLogEntry(entry, useJson));
+            }
+            globalAggregator.add(entry);
+        },
+        error: (message, error, context) => {
+            const entry = createLogEntry(LogLevel.ERROR, message, context, error);
+            if (shouldLog(LogLevel.ERROR)) {
+                console.error(formatLogEntry(entry, useJson));
+                if (error && !useJson) {
+                    console.error(error);
+                }
+            }
+            globalAggregator.add(entry);
+        },
+        info: (message, context) => {
+            const entry = createLogEntry(LogLevel.INFO, message, context);
+            if (shouldLog(LogLevel.INFO)) {
+                console.info(formatLogEntry(entry, useJson));
+            }
+            globalAggregator.add(entry);
+        },
+        debug: (message, context) => {
+            const entry = createLogEntry(LogLevel.DEBUG, message, context);
+            if (shouldLog(LogLevel.DEBUG)) {
+                console.debug(formatLogEntry(entry, useJson));
+            }
+            globalAggregator.add(entry);
+        },
+        auditLog: (event) => {
+            const entry = createLogEntry(LogLevel.AUDIT, formatAuditEvent(event, false));
+            if (shouldLog(LogLevel.AUDIT) || process.env.AUDIT_LOG === 'true') {
+                console.log(formatAuditEvent(event, useJson));
+            }
+            globalAggregator.add(entry);
+            globalAggregator.addAudit(event);
+        },
+        securityLog: (event) => {
+            const entry = createLogEntry(LogLevel.SECURITY, formatSecurityEvent(event, false));
+            // Security events always log unless in test mode
+            if (process.env.NODE_ENV !== 'test') {
+                console.warn(formatSecurityEvent(event, useJson));
+            }
+            globalAggregator.add(entry);
+            globalAggregator.addSecurity(event);
+        },
+    };
+}
+/**
+ * Default logger instance
+ *
+ * Environment variables:
+ * - NODE_ENV=test: Suppress warn/info/debug output
+ * - DEBUG=true: Enable info and debug output
+ * - LOG_FORMAT=json: Output logs in JSON format
+ * - LOG_LEVEL=0-5: Minimum log level to output
+ * - AUDIT_LOG=true: Enable audit log output
+ *
+ * @example
+ * ```typescript
+ * logger.info('Processing skill', { skillId: 'foo' })
+ * logger.error('Failed to fetch', new Error('Network error'))
+ * logger.auditLog({
+ *   eventType: 'skill.install',
+ *   timestamp: new Date().toISOString(),
+ *   actor: 'user',
+ *   resource: 'skill-id',
+ *   action: 'install',
+ *   result: 'success'
+ * })
+ * ```
+ */
+export const logger = createLoggerInstance();
+/**
+ * Create a namespaced logger
+ *
+ * @param namespace - The namespace prefix for log messages
+ * @returns A Logger instance with namespaced messages
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('GitLabAdapter')
+ * log.warn('Rate limit exceeded', { remaining: 0 })
+ * log.auditLog({
+ *   eventType: 'adapter.request',
+ *   timestamp: new Date().toISOString(),
+ *   actor: 'GitLabAdapter',
+ *   resource: 'https://gitlab.com/api/v4/projects',
+ *   action: 'fetch',
+ *   result: 'success'
+ * })
+ * ```
+ */
+export function createLogger(namespace) {
+    return createLoggerInstance(namespace);
+}
+/**
+ * No-op logger for testing or silent operation
+ */
+export const silentLogger = {
+    warn: () => { },
+    error: () => { },
+    info: () => { },
+    debug: () => { },
+    auditLog: () => { },
+    securityLog: () => { },
+};
+/**
+ * Helper to create audit events with current timestamp
+ */
+export function createAuditEvent(eventType, actor, resource, action, result, metadata) {
+    return {
+        eventType,
+        timestamp: new Date().toISOString(),
+        actor,
+        resource,
+        action,
+        result,
+        metadata,
+    };
+}
+/**
+ * Helper to create security events with current timestamp
+ */
+export function createSecurityEvent(eventType, severity, resource, action, details, metadata) {
+    return {
+        eventType,
+        timestamp: new Date().toISOString(),
+        severity,
+        resource,
+        action,
+        details,
+        metadata,
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

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

package/dist/utils/rate-limit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Rate Limiter Utility (SMI-4316)
+ *
+ * Token-bucket style rate limiter intended for gating log output. First N
+ * events per window fire unconditionally; after that, one-in-`SAMPLE_EVERY`
+ * is allowed through. Windows reset automatically once `WINDOW_MS` elapses
+ * since the first event in the window.
+ *
+ * Keyed: callers pass a stable string key (e.g. file path or error
+ * signature). Different keys are isolated — a flood on key A does not
+ * starve key B.
+ *
+ * Intended for observability, not security-sensitive throttling.
+ */
+type Key = string;
+/** Window length for a single bucket (1 hour). */
+export declare const WINDOW_MS: number;
+/** First N events per window always pass through. */
+export declare const FIRST_N = 5;
+/** After the first N, every Nth subsequent event passes through. */
+export declare const SAMPLE_EVERY = 100;
+/**
+ * Return `true` if the event for `key` should be allowed through
+ * (logged / processed), or `false` if it is suppressed by the limiter.
+ *
+ * The first `FIRST_N` events in a window always return `true`. After that,
+ * one-in-`SAMPLE_EVERY` events return `true` until the window rolls over.
+ *
+ * @param key - Stable grouping key (per-file, per-error, etc.)
+ * @param now - Optional timestamp override for tests (defaults to Date.now()).
+ */
+export declare function rateLimited(key: Key, now?: number): boolean;
+/**
+ * Reset all buckets. Intended for tests; callers in production should not
+ * need this.
+ */
+export declare function resetRateLimiter(): void;
+export {};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/utils/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,GAAG,GAAG,MAAM,CAAA;AASjB,kDAAkD;AAClD,eAAO,MAAM,SAAS,QAAiB,CAAA;AAEvC,qDAAqD;AACrD,eAAO,MAAM,OAAO,IAAI,CAAA;AAExB,oEAAoE;AACpE,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO,CASvE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/utils/rate-limit.js

@@ -0,0 +1,48 @@
+/**
+ * Rate Limiter Utility (SMI-4316)
+ *
+ * Token-bucket style rate limiter intended for gating log output. First N
+ * events per window fire unconditionally; after that, one-in-`SAMPLE_EVERY`
+ * is allowed through. Windows reset automatically once `WINDOW_MS` elapses
+ * since the first event in the window.
+ *
+ * Keyed: callers pass a stable string key (e.g. file path or error
+ * signature). Different keys are isolated — a flood on key A does not
+ * starve key B.
+ *
+ * Intended for observability, not security-sensitive throttling.
+ */
+const BUCKETS = new Map();
+/** Window length for a single bucket (1 hour). */
+export const WINDOW_MS = 60 * 60 * 1000;
+/** First N events per window always pass through. */
+export const FIRST_N = 5;
+/** After the first N, every Nth subsequent event passes through. */
+export const SAMPLE_EVERY = 100;
+/**
+ * Return `true` if the event for `key` should be allowed through
+ * (logged / processed), or `false` if it is suppressed by the limiter.
+ *
+ * The first `FIRST_N` events in a window always return `true`. After that,
+ * one-in-`SAMPLE_EVERY` events return `true` until the window rolls over.
+ *
+ * @param key - Stable grouping key (per-file, per-error, etc.)
+ * @param now - Optional timestamp override for tests (defaults to Date.now()).
+ */
+export function rateLimited(key, now = Date.now()) {
+    const existing = BUCKETS.get(key);
+    const bucket = existing && now - existing.windowStart <= WINDOW_MS ? existing : { count: 0, windowStart: now };
+    bucket.count += 1;
+    BUCKETS.set(key, bucket);
+    if (bucket.count <= FIRST_N)
+        return true;
+    return (bucket.count - FIRST_N) % SAMPLE_EVERY === 1;
+}
+/**
+ * Reset all buckets. Intended for tests; callers in production should not
+ * need this.
+ */
+export function resetRateLimiter() {
+    BUCKETS.clear();
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/utils/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/utils/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAA;AAE3C,kDAAkD;AAClD,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAEvC,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAA;AAExB,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAA;AAE/B;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,GAAQ,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACjC,MAAM,MAAM,GACV,QAAQ,IAAI,GAAG,GAAG,QAAQ,CAAC,WAAW,IAAI,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE,CAAA;IACjG,MAAM,CAAC,KAAK,IAAI,CAAC,CAAA;IACjB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;IAExB,IAAI,MAAM,CAAC,KAAK,IAAI,OAAO;QAAE,OAAO,IAAI,CAAA;IACxC,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC,CAAA;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,KAAK,EAAE,CAAA;AACjB,CAAC"}

package/dist/utils/rate-limit.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SMI-4316: rateLimited() unit tests.
+ *
+ * Covers:
+ *   1. First-N events (<= FIRST_N) always return true.
+ *   2. Sampled-after-N events follow the 1-in-SAMPLE_EVERY cadence.
+ *   3. Per-key isolation (one key's flood does not starve another key).
+ *   4. Window rollover when `now` advances beyond WINDOW_MS.
+ */
+export {};
+//# sourceMappingURL=rate-limit.test.d.ts.map

package/dist/utils/rate-limit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.test.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limit.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/utils/rate-limit.test.js

@@ -0,0 +1,86 @@
+/**
+ * SMI-4316: rateLimited() unit tests.
+ *
+ * Covers:
+ *   1. First-N events (<= FIRST_N) always return true.
+ *   2. Sampled-after-N events follow the 1-in-SAMPLE_EVERY cadence.
+ *   3. Per-key isolation (one key's flood does not starve another key).
+ *   4. Window rollover when `now` advances beyond WINDOW_MS.
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+import { FIRST_N, SAMPLE_EVERY, WINDOW_MS, rateLimited, resetRateLimiter } from './rate-limit.js';
+describe('rateLimited', () => {
+    afterEach(() => {
+        resetRateLimiter();
+    });
+    it('allows the first FIRST_N calls for a key', () => {
+        const results = [];
+        for (let i = 0; i < FIRST_N; i += 1) {
+            results.push(rateLimited('k1'));
+        }
+        expect(results.every((r) => r === true)).toBe(true);
+    });
+    it('after FIRST_N, allows one-in-SAMPLE_EVERY', () => {
+        // Burn the first N allowed events.
+        for (let i = 0; i < FIRST_N; i += 1)
+            rateLimited('k2');
+        // Next 2 * SAMPLE_EVERY events should produce exactly 2 allowed.
+        let allowed = 0;
+        for (let i = 0; i < 2 * SAMPLE_EVERY; i += 1) {
+            if (rateLimited('k2'))
+                allowed += 1;
+        }
+        expect(allowed).toBe(2);
+    });
+    it('matches the plan count: 5 firsts + 200 sampled = 7 total allowed', () => {
+        // Mirrors the acceptance test described in the plan.
+        let allowed = 0;
+        for (let i = 0; i < FIRST_N; i += 1) {
+            if (rateLimited('k3'))
+                allowed += 1;
+        }
+        for (let i = 0; i < 200; i += 1) {
+            if (rateLimited('k3'))
+                allowed += 1;
+        }
+        expect(allowed).toBe(FIRST_N + 2);
+    });
+    it('isolates per-key: flooding one key does not starve another', () => {
+        // Flood key A well past FIRST_N.
+        for (let i = 0; i < FIRST_N * 3; i += 1)
+            rateLimited('A');
+        // Key B still gets its full FIRST_N window.
+        let bAllowed = 0;
+        for (let i = 0; i < FIRST_N; i += 1) {
+            if (rateLimited('B'))
+                bAllowed += 1;
+        }
+        expect(bAllowed).toBe(FIRST_N);
+    });
+    it('resets the bucket when the window elapses', () => {
+        const t0 = 1_000_000;
+        // Exhaust first window at t0.
+        for (let i = 0; i < FIRST_N; i += 1)
+            rateLimited('win', t0);
+        // Next event at t0 is the first sampled hit (count-FIRST_N === 1),
+        // so it passes. Step past that so the next is definitely suppressed.
+        rateLimited('win', t0);
+        expect(rateLimited('win', t0)).toBe(false);
+        // Advance past WINDOW_MS — the next call starts a fresh bucket and
+        // returns true as count-1.
+        const t1 = t0 + WINDOW_MS + 1;
+        expect(rateLimited('win', t1)).toBe(true);
+    });
+    it('suppresses events after FIRST_N + 1 that are not on the sampled boundary', () => {
+        const t = 5_000;
+        // First N pass.
+        for (let i = 0; i < FIRST_N; i += 1) {
+            expect(rateLimited('same-now', t)).toBe(true);
+        }
+        // FIRST_N + 1: first sampled hit, (count - FIRST_N) % SAMPLE_EVERY === 1 → true.
+        expect(rateLimited('same-now', t)).toBe(true);
+        // FIRST_N + 2: (count - FIRST_N) % SAMPLE_EVERY === 2 → false.
+        expect(rateLimited('same-now', t)).toBe(false);
+    });
+});
+//# sourceMappingURL=rate-limit.test.js.map