@tracehound/core 1.2.0

package/dist/core/s3-cold-storage.d.ts

@@ -0,0 +1,116 @@
+/**
+ * S3-Compatible Cold Storage Adapter
+ *
+ * Implements IColdStorageAdapter for any S3-compatible object store:
+ * AWS S3, Cloudflare R2, Google Cloud Storage (S3-compat), MinIO, etc.
+ *
+ * DESIGN:
+ * - Zero AWS SDK dependency. Client is injected via S3LikeClient interface.
+ * - Binary envelope format: self-contained, no sidecar files needed.
+ * - Async encode/decode via Phase 4 Async Codec.
+ *
+ * RFC-0000 INVARIANTS:
+ * - write() is fire-and-forget (caller does not wait for confirmation)
+ * - Adapter errors are caught and returned, never thrown
+ * - Payload integrity is preserved via binary envelope with embedded hash
+ */
+import type { EncodedPayload } from '../utils/binary-codec.js';
+import type { ColdStorageReadResult, ColdStorageWriteResult, IColdStorageAdapter } from './cold-storage.js';
+/**
+ * Minimal S3-compatible client interface.
+ *
+ * Users provide their own implementation using @aws-sdk/client-s3,
+ * Cloudflare R2 bindings, MinIO client, or any S3-compatible SDK.
+ *
+ * @example
+ * // AWS S3
+ * import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadBucketCommand } from '@aws-sdk/client-s3'
+ * const s3 = new S3Client({ region: 'us-east-1' })
+ * const client: S3LikeClient = {
+ *   putObject: (p) => s3.send(new PutObjectCommand(p)).then(() => {}),
+ *   getObject: (p) => s3.send(new GetObjectCommand(p)).then(r => ({
+ *     Body: new Uint8Array(await r.Body!.transformToByteArray())
+ *   })),
+ *   deleteObject: (p) => s3.send(new DeleteObjectCommand(p)).then(() => {}),
+ *   headBucket: (p) => s3.send(new HeadBucketCommand(p)).then(() => {}),
+ * }
+ */
+export interface S3LikeClient {
+    putObject(params: {
+        Bucket: string;
+        Key: string;
+        Body: Uint8Array;
+        ContentType?: string;
+    }): Promise<void>;
+    getObject(params: {
+        Bucket: string;
+        Key: string;
+    }): Promise<{
+        Body: Uint8Array;
+    }>;
+    deleteObject(params: {
+        Bucket: string;
+        Key: string;
+    }): Promise<void>;
+    headBucket(params: {
+        Bucket: string;
+    }): Promise<void>;
+}
+/**
+ * S3 cold storage configuration.
+ */
+export interface S3ColdStorageConfig {
+    /** Pre-configured S3-compatible client (injected, not owned) */
+    client: S3LikeClient;
+    /** Target bucket name */
+    bucket: string;
+    /** Key prefix for all evidence objects (e.g., 'tracehound/evidence/') */
+    prefix?: string;
+}
+declare const HEADER_SIZE = 78;
+/**
+ * Pack EncodedPayload into a self-contained binary envelope.
+ * Used for storage — all metadata is embedded, no sidecar needed.
+ */
+declare function packEnvelope(payload: EncodedPayload): Uint8Array;
+/**
+ * Unpack binary envelope back to EncodedPayload.
+ * Returns null if envelope is invalid (wrong magic, version, or size mismatch).
+ */
+declare function unpackEnvelope(data: Uint8Array): EncodedPayload | null;
+/**
+ * S3-compatible cold storage adapter.
+ *
+ * Stores evidence as binary envelopes in any S3-compatible object store.
+ * Client is injected — no AWS SDK dependency in core.
+ *
+ * @example
+ * const adapter = new S3ColdStorage({
+ *   client: myS3Client,
+ *   bucket: 'tracehound-evidence',
+ *   prefix: 'prod/evidence/',
+ * })
+ */
+export declare class S3ColdStorage implements IColdStorageAdapter {
+    private readonly client;
+    private readonly bucket;
+    private readonly prefix;
+    constructor(config: S3ColdStorageConfig);
+    /**
+     * Resolve storage key for an evidence ID.
+     */
+    private key;
+    write(id: string, payload: EncodedPayload): Promise<ColdStorageWriteResult>;
+    read(id: string): Promise<ColdStorageReadResult>;
+    delete(id: string): Promise<boolean>;
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Create an S3-compatible cold storage adapter.
+ *
+ * @param config - S3 client, bucket, and optional key prefix
+ * @returns IColdStorageAdapter backed by S3-compatible storage
+ */
+export declare function createS3ColdStorage(config: S3ColdStorageConfig): IColdStorageAdapter;
+export { HEADER_SIZE, packEnvelope, unpackEnvelope };
+//# sourceMappingURL=s3-cold-storage.d.ts.map

package/dist/core/s3-cold-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3-cold-storage.d.ts","sourceRoot":"","sources":["../../src/core/s3-cold-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAC9D,OAAO,KAAK,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAM3G;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,GAAG,EAAE,MAAM,CAAA;QACX,IAAI,EAAE,UAAU,CAAA;QAChB,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB,SAAS,CAAC,MAAM,EAAE;QAChB,MAAM,EAAE,MAAM,CAAA;QACd,GAAG,EAAE,MAAM,CAAA;KACZ,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAA;KAAE,CAAC,CAAA;IAEjC,YAAY,CAAC,MAAM,EAAE;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,GAAG,EAAE,MAAM,CAAA;KACZ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB,UAAU,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClB;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,MAAM,EAAE,YAAY,CAAA;IACpB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAoBD,QAAA,MAAM,WAAW,KAAK,CAAA;AAEtB;;;GAGG;AACH,iBAAS,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,UAAU,CAwBzD;AAED;;;GAGG;AACH,iBAAS,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAyC/D;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,MAAM,EAAE,mBAAmB;IAMvC;;OAEG;IACH,OAAO,CAAC,GAAG;IAIL,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAmB3E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBhD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAepC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;CAQtC;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAEpF;AAGD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,CAAA"}

package/dist/core/s3-cold-storage.js

@@ -0,0 +1,198 @@
+/**
+ * S3-Compatible Cold Storage Adapter
+ *
+ * Implements IColdStorageAdapter for any S3-compatible object store:
+ * AWS S3, Cloudflare R2, Google Cloud Storage (S3-compat), MinIO, etc.
+ *
+ * DESIGN:
+ * - Zero AWS SDK dependency. Client is injected via S3LikeClient interface.
+ * - Binary envelope format: self-contained, no sidecar files needed.
+ * - Async encode/decode via Phase 4 Async Codec.
+ *
+ * RFC-0000 INVARIANTS:
+ * - write() is fire-and-forget (caller does not wait for confirmation)
+ * - Adapter errors are caught and returned, never thrown
+ * - Payload integrity is preserved via binary envelope with embedded hash
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Binary Envelope Format
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Offset  Size  Description
+// ──────  ────  ────────────────────────
+//  0       4    Magic: 0x54 0x48 0x43 0x53 ("THCS")
+//  4       2    Version: 0x00 0x01
+//  6       4    originalSize (uint32 BE)
+// 10       4    compressedSize (uint32 BE)
+// 14      64    SHA-256 hash (hex ASCII, 64 bytes)
+// 78       N    compressed gzip data
+//
+// Total header: 78 bytes
+// ─────────────────────────────────────────────────────────────────────────────
+const ENVELOPE_MAGIC = new Uint8Array([0x54, 0x48, 0x43, 0x53]); // "THCS"
+const ENVELOPE_VERSION = 1;
+const HEADER_SIZE = 78;
+/**
+ * Pack EncodedPayload into a self-contained binary envelope.
+ * Used for storage — all metadata is embedded, no sidecar needed.
+ */
+function packEnvelope(payload) {
+    const envelope = new Uint8Array(HEADER_SIZE + payload.compressedSize);
+    const view = new DataView(envelope.buffer);
+    // Magic
+    envelope.set(ENVELOPE_MAGIC, 0);
+    // Version
+    view.setUint16(4, ENVELOPE_VERSION, false); // big-endian
+    // originalSize
+    view.setUint32(6, payload.originalSize, false);
+    // compressedSize
+    view.setUint32(10, payload.compressedSize, false);
+    // Hash (64 ASCII hex chars)
+    const hashBytes = new TextEncoder().encode(payload.hash);
+    envelope.set(hashBytes, 14);
+    // Compressed data
+    envelope.set(payload.compressed, HEADER_SIZE);
+    return envelope;
+}
+/**
+ * Unpack binary envelope back to EncodedPayload.
+ * Returns null if envelope is invalid (wrong magic, version, or size mismatch).
+ */
+function unpackEnvelope(data) {
+    if (data.length < HEADER_SIZE) {
+        return null;
+    }
+    // Verify magic
+    for (let i = 0; i < 4; i++) {
+        if (data[i] !== ENVELOPE_MAGIC[i]) {
+            return null;
+        }
+    }
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    // Verify version
+    const version = view.getUint16(4, false);
+    if (version !== ENVELOPE_VERSION) {
+        return null;
+    }
+    const originalSize = view.getUint32(6, false);
+    const compressedSize = view.getUint32(10, false);
+    // Verify data length matches
+    if (data.length !== HEADER_SIZE + compressedSize) {
+        return null;
+    }
+    // Extract hash
+    const hashBytes = data.slice(14, 78);
+    const hash = new TextDecoder().decode(hashBytes);
+    // Extract compressed data
+    const compressed = data.slice(HEADER_SIZE, HEADER_SIZE + compressedSize);
+    return {
+        compressed,
+        hash,
+        originalSize,
+        compressedSize,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// S3 Cold Storage Adapter
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * S3-compatible cold storage adapter.
+ *
+ * Stores evidence as binary envelopes in any S3-compatible object store.
+ * Client is injected — no AWS SDK dependency in core.
+ *
+ * @example
+ * const adapter = new S3ColdStorage({
+ *   client: myS3Client,
+ *   bucket: 'tracehound-evidence',
+ *   prefix: 'prod/evidence/',
+ * })
+ */
+export class S3ColdStorage {
+    client;
+    bucket;
+    prefix;
+    constructor(config) {
+        this.client = config.client;
+        this.bucket = config.bucket;
+        this.prefix = config.prefix ?? 'tracehound/evidence/';
+    }
+    /**
+     * Resolve storage key for an evidence ID.
+     */
+    key(id) {
+        return `${this.prefix}${id}.thcs`;
+    }
+    async write(id, payload) {
+        try {
+            const envelope = packEnvelope(payload);
+            const key = this.key(id);
+            await this.client.putObject({
+                Bucket: this.bucket,
+                Key: key,
+                Body: envelope,
+                ContentType: 'application/octet-stream',
+            });
+            return { success: true, id: key };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown S3 write error';
+            return { success: false, error: message };
+        }
+    }
+    async read(id) {
+        try {
+            const key = this.key(id);
+            const response = await this.client.getObject({
+                Bucket: this.bucket,
+                Key: key,
+            });
+            const payload = unpackEnvelope(response.Body);
+            if (!payload) {
+                return { success: false, error: 'Invalid envelope format' };
+            }
+            return { success: true, payload };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown S3 read error';
+            return { success: false, error: message };
+        }
+    }
+    async delete(id) {
+        try {
+            const key = this.key(id);
+            await this.client.deleteObject({
+                Bucket: this.bucket,
+                Key: key,
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isAvailable() {
+        try {
+            await this.client.headBucket({ Bucket: this.bucket });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory + Exports
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create an S3-compatible cold storage adapter.
+ *
+ * @param config - S3 client, bucket, and optional key prefix
+ * @returns IColdStorageAdapter backed by S3-compatible storage
+ */
+export function createS3ColdStorage(config) {
+    return new S3ColdStorage(config);
+}
+// Re-export envelope utilities for advanced use cases (custom adapters)
+export { HEADER_SIZE, packEnvelope, unpackEnvelope };
+//# sourceMappingURL=s3-cold-storage.js.map

package/dist/core/s3-cold-storage.js.map

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

package/dist/core/scheduler.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Tick Scheduler - jittered task scheduling for background operations.
+ *
+ * RFC-0000 CRITICAL INVARIANTS:
+ * - skipIfBusy: true by default (prevents timing attacks)
+ * - Jitter applied to all ticks (prevents predictable patterns)
+ * - No blocking of hot-path
+ */
+/**
+ * Scheduled task definition.
+ */
+export interface ScheduledTask {
+    /** Unique task identifier */
+    id: string;
+    /** Task execution function */
+    execute: () => void | Promise<void>;
+    /** Interval between executions in ms */
+    intervalMs: number;
+    /** Priority (lower = higher priority) */
+    priority?: number;
+}
+/**
+ * Tick Scheduler configuration.
+ */
+export interface TickSchedulerConfig {
+    /** Base tick interval in ms */
+    tickInterval: number;
+    /** Maximum jitter range in ms (added to tick interval) */
+    jitterMs: number;
+    /**
+     * Skip tick if system is busy.
+     * DEFAULT: true (RFC requirement for timing attack prevention)
+     */
+    skipIfBusy?: boolean;
+}
+/**
+ * Scheduler statistics (immutable snapshot).
+ */
+export interface SchedulerStats {
+    /** Total ticks executed */
+    totalTicks: number;
+    /** Total tasks executed */
+    totalTasksExecuted: number;
+    /** Total ticks skipped (due to busy) */
+    skippedTicks: number;
+    /** Number of scheduled tasks */
+    scheduledTasks: number;
+    /** Whether scheduler is running */
+    running: boolean;
+    /** Whether system is currently busy */
+    busy: boolean;
+}
+/**
+ * Busy check function type.
+ * Returns true if system is busy.
+ */
+export type BusyChecker = () => boolean;
+/**
+ * Scheduler interface.
+ */
+export interface IScheduler {
+    /**
+     * Start the scheduler.
+     */
+    start(): void;
+    /**
+     * Stop the scheduler.
+     */
+    stop(): void;
+    /**
+     * Schedule a task.
+     *
+     * @param task - Task definition
+     */
+    schedule(task: ScheduledTask): void;
+    /**
+     * Unschedule a task by ID.
+     *
+     * @param taskId - Task ID to remove
+     */
+    unschedule(taskId: string): void;
+    /**
+     * Set busy checker function.
+     * Used to determine if ticks should be skipped.
+     *
+     * @param checker - Function that returns true if busy
+     */
+    setBusyChecker(checker: BusyChecker): void;
+    /**
+     * Get scheduler statistics (immutable snapshot).
+     */
+    readonly stats: Readonly<SchedulerStats>;
+}
+/**
+ * Tick Scheduler implementation.
+ */
+export declare class Scheduler implements IScheduler {
+    private readonly config;
+    private readonly tasks;
+    private tickTimeoutId;
+    private busyChecker;
+    private _running;
+    private _busy;
+    private _totalTicks;
+    private _totalTasksExecuted;
+    private _skippedTicks;
+    private readonly skipIfBusy;
+    constructor(config: TickSchedulerConfig);
+    start(): void;
+    stop(): void;
+    schedule(task: ScheduledTask): void;
+    unschedule(taskId: string): void;
+    setBusyChecker(checker: BusyChecker): void;
+    get stats(): Readonly<SchedulerStats>;
+    private scheduleTick;
+    private executeTick;
+    private getDueTasks;
+    private executeTask;
+}
+/**
+ * Create a Scheduler instance.
+ *
+ * @param config - Scheduler configuration
+ */
+export declare function createScheduler(config: TickSchedulerConfig): IScheduler;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/core/scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,8BAA8B;IAC9B,OAAO,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAA;IACtB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAA;AAEvC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;IAEb;;OAEG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;IAEnC;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IAE1C;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;CACzC;AAcD;;GAEG;AACH,qBAAa,SAAU,YAAW,UAAU;IAe9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,aAAa,CAA6C;IAClE,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAQ;IAGrB,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,aAAa,CAAI;IAGzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,MAAM,EAAE,mBAAmB;IAKxD,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IAUZ,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAOnC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIhC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAI1C,IAAI,KAAK,IAAI,QAAQ,CAAC,cAAc,CAAC,CASpC;IAID,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,WAAW;IA6BnB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,WAAW;CAiBpB;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,UAAU,CAEvE"}

package/dist/core/scheduler.js

@@ -0,0 +1,138 @@
+/**
+ * Tick Scheduler - jittered task scheduling for background operations.
+ *
+ * RFC-0000 CRITICAL INVARIANTS:
+ * - skipIfBusy: true by default (prevents timing attacks)
+ * - Jitter applied to all ticks (prevents predictable patterns)
+ * - No blocking of hot-path
+ */
+/**
+ * Tick Scheduler implementation.
+ */
+export class Scheduler {
+    config;
+    tasks = new Map();
+    tickTimeoutId = null;
+    busyChecker = () => false;
+    _running = false;
+    _busy = false;
+    // Statistics
+    _totalTicks = 0;
+    _totalTasksExecuted = 0;
+    _skippedTicks = 0;
+    // Config with defaults
+    skipIfBusy;
+    constructor(config) {
+        this.config = config;
+        // skipIfBusy defaults to true (RFC requirement)
+        this.skipIfBusy = config.skipIfBusy ?? true;
+    }
+    start() {
+        if (this._running)
+            return;
+        this._running = true;
+        this.scheduleTick();
+    }
+    stop() {
+        if (!this._running)
+            return;
+        this._running = false;
+        if (this.tickTimeoutId) {
+            clearTimeout(this.tickTimeoutId);
+            this.tickTimeoutId = null;
+        }
+    }
+    schedule(task) {
+        this.tasks.set(task.id, {
+            task,
+            lastExecuted: 0,
+        });
+    }
+    unschedule(taskId) {
+        this.tasks.delete(taskId);
+    }
+    setBusyChecker(checker) {
+        this.busyChecker = checker;
+    }
+    get stats() {
+        return Object.freeze({
+            totalTicks: this._totalTicks,
+            totalTasksExecuted: this._totalTasksExecuted,
+            skippedTicks: this._skippedTicks,
+            scheduledTasks: this.tasks.size,
+            running: this._running,
+            busy: this._busy,
+        });
+    }
+    // ─── Private Methods ───────────────────────────────────────────────────────
+    scheduleTick() {
+        if (!this._running)
+            return;
+        // Apply jitter to interval
+        const jitter = Math.random() * this.config.jitterMs;
+        const delay = this.config.tickInterval + jitter;
+        this.tickTimeoutId = setTimeout(() => {
+            this.executeTick();
+        }, delay);
+    }
+    executeTick() {
+        if (!this._running)
+            return;
+        this._totalTicks++;
+        // Check if system is busy
+        this._busy = this.busyChecker();
+        if (this.skipIfBusy && this._busy) {
+            this._skippedTicks++;
+            this.scheduleTick();
+            return;
+        }
+        // Execute due tasks
+        const now = Date.now();
+        const dueTasks = this.getDueTasks(now);
+        // Sort by priority
+        dueTasks.sort((a, b) => (a.task.priority ?? 100) - (b.task.priority ?? 100));
+        for (const taskState of dueTasks) {
+            this.executeTask(taskState, now);
+        }
+        // Schedule next tick
+        this.scheduleTick();
+    }
+    getDueTasks(now) {
+        const dueTasks = [];
+        for (const [, taskState] of this.tasks) {
+            const elapsed = now - taskState.lastExecuted;
+            if (elapsed >= taskState.task.intervalMs) {
+                dueTasks.push(taskState);
+            }
+        }
+        return dueTasks;
+    }
+    executeTask(taskState, now) {
+        taskState.lastExecuted = now;
+        this._totalTasksExecuted++;
+        try {
+            const result = taskState.task.execute();
+            // Handle async tasks (fire-and-forget)
+            if (result instanceof Promise) {
+                result.catch(() => {
+                    // Silently ignore task errors
+                });
+            }
+        }
+        catch {
+            // Silently ignore task errors
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a Scheduler instance.
+ *
+ * @param config - Scheduler configuration
+ */
+export function createScheduler(config) {
+    return new Scheduler(config);
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/core/scheduler.js.map

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