@agentick/core 0.0.1

package/dist/core/context.js

@@ -0,0 +1,290 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { EventEmitter } from "node:events";
+import {} from "./channel";
+import { ProcedureGraph } from "./procedure-graph";
+import { ContextError } from "@tentickle/shared";
+const storage = new AsyncLocalStorage();
+/**
+ * Global event subscribers that receive ALL context events across all contexts.
+ * Use `Context.subscribeGlobal()` to register a subscriber.
+ */
+const globalSubscribers = new Set();
+/**
+ * Static class for managing execution context via AsyncLocalStorage.
+ *
+ * Context flows automatically through all async operations without explicit passing.
+ * Use `Context.run()` to establish context, and `Context.get()` to access it.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Create and run with context
+ * const ctx = Context.create({ user: { id: 'user-1' } });
+ * await Context.run(ctx, async () => {
+ *   const current = Context.get();
+ *   console.log(current.user?.id); // 'user-1'
+ *
+ *   // Context flows to nested calls
+ *   await someAsyncFunction(); // Can access Context.get() inside
+ * });
+ * ```
+ *
+ * @example Parallel execution with child contexts
+ * ```typescript
+ * // Each parallel task gets its own context to avoid races
+ * const [a, b] = await Promise.all([
+ *   Context.fork({ procedurePid: 'task-1' }, () => doTask1()),
+ *   Context.fork({ procedurePid: 'task-2' }, () => doTask2()),
+ * ]);
+ * ```
+ *
+ * @example Emitting events
+ * ```typescript
+ * // Events go to both global bus and operation handle
+ * Context.emit('progress', { percent: 50 }, 'my-tool');
+ * ```
+ *
+ * @see {@link KernelContext} - The context interface
+ * @see {@link context} - Brand an object as context for procedure detection
+ */
+export class Context {
+    /**
+     * Creates a new root context with default values.
+     *
+     * @param overrides - Partial context to merge with defaults
+     * @returns A new KernelContext
+     *
+     * @example
+     * ```typescript
+     * const ctx = Context.create({
+     *   user: { id: 'user-1' },
+     *   metadata: { feature: 'chat' }
+     * });
+     * ```
+     */
+    static create(overrides = {}) {
+        return this.brand({
+            requestId: overrides.requestId ?? crypto.randomUUID(),
+            traceId: overrides.traceId ?? crypto.randomUUID(),
+            metadata: overrides.metadata ?? {},
+            metrics: {},
+            events: new EventEmitter(),
+            user: overrides.user,
+            signal: overrides.signal,
+            executionHandle: overrides.executionHandle,
+            // Tentickle middleware registry (for context-based middleware resolution)
+            middleware: overrides.middleware,
+            // Execution context fields (Phase 3)
+            executionId: overrides.executionId,
+            executionType: overrides.executionType,
+            parentExecutionId: overrides.parentExecutionId,
+        });
+    }
+    static brand(ctx) {
+        if (!isKernelContext(ctx)) {
+            return { ...ctx, [KERNEL_CONTEXT_SYMBOL]: true };
+        }
+        return ctx;
+    }
+    /**
+     * Runs a function within the given context.
+     * All async operations within `fn` will have access to this context.
+     *
+     * @param context - The context to run within
+     * @param fn - Async function to execute
+     * @returns The result of the function
+     */
+    static run(ctx, fn) {
+        return storage.run((isKernelContext(ctx) ? ctx : Context.create(ctx)), fn);
+    }
+    /**
+     * Creates a child context that inherits from the current context (or creates a new root).
+     * The child context is a shallow copy - objects like `events`, `procedureGraph`, and `channels`
+     * are shared with the parent (intentionally, for coordination).
+     *
+     * Scalar values like `procedurePid`, `procedureNode`, and `origin` can be safely
+     * overridden in the child without affecting the parent.
+     *
+     * @param overrides - Properties to override in the child context
+     * @returns A new context object inheriting from the current context
+     *
+     * @example
+     * ```typescript
+     * // Create child context with new procedure ID
+     * const childCtx = Context.child({ procedurePid: 'new-pid' });
+     * await Context.run(childCtx, async () => {
+     *   // This context has its own procedurePid but shares events, graph, etc.
+     * });
+     * ```
+     */
+    static child(overrides = {}) {
+        const parent = Context.tryGet();
+        if (!parent) {
+            // No parent context - create a new root context
+            return Context.create(overrides);
+        }
+        // Create shallow copy of parent, then apply overrides
+        return this.brand({
+            ...parent,
+            ...overrides,
+        });
+    }
+    /**
+     * Creates a child context and runs a function within it.
+     * Convenience method combining `child()` and `run()`.
+     *
+     * This is the safe way to run parallel procedures - each gets its own
+     * context object so mutations don't race.
+     *
+     * @param overrides - Properties to override in the child context
+     * @param fn - Function to run within the child context
+     * @returns The result of the function
+     *
+     * @example
+     * ```typescript
+     * // Run parallel procedures safely
+     * const [result1, result2] = await Promise.all([
+     *   Context.fork({ procedurePid: 'proc-1' }, async () => doWork1()),
+     *   Context.fork({ procedurePid: 'proc-2' }, async () => doWork2()),
+     * ]);
+     * ```
+     */
+    static fork(overrides, fn) {
+        const childCtx = Context.child(overrides);
+        return Context.run(childCtx, fn);
+    }
+    /**
+     * Gets the current context. Throws if not found.
+     */
+    static get() {
+        const store = storage.getStore();
+        if (!store) {
+            throw ContextError.notFound();
+        }
+        return store;
+    }
+    /**
+     * Gets the current context or returns undefined if not found.
+     */
+    static tryGet() {
+        return storage.getStore();
+    }
+    /**
+     * Set the current tick number in the context.
+     * Called by the engine at the start of each tick.
+     */
+    static setTick(tick) {
+        const ctx = this.tryGet();
+        if (ctx) {
+            ctx.tick = tick;
+        }
+    }
+    /**
+     * Helper to emit an event on the current context.
+     * Events are broadcast to:
+     * 1. The context's local event bus (ctx.events)
+     * 2. The operation handle (ctx.executionHandle) if present
+     * 3. All global subscribers registered via subscribeGlobal()
+     */
+    static emit(type, payload, source = "system") {
+        const ctx = this.tryGet();
+        if (ctx) {
+            const event = {
+                type,
+                payload,
+                timestamp: Date.now(),
+                source,
+                // Correlation IDs for distributed tracing
+                traceId: ctx.traceId,
+                requestId: ctx.requestId,
+                // Execution context (for execution tree building)
+                executionId: ctx.executionId,
+                parentExecutionId: ctx.parentExecutionId,
+                procedureId: ctx.procedurePid,
+                tick: ctx.tick,
+                // User context (for multi-tenant telemetry)
+                userId: ctx.user?.id,
+                tenantId: ctx.user?.tenantId,
+            };
+            // 1. Emit to the Global Request Bus
+            ctx.events.emit(type, event);
+            ctx.events.emit("*", event);
+            // 2. Emit to the Operation Handle (if exists and is an EventEmitter)
+            if (ctx.executionHandle) {
+                ctx.executionHandle.emit?.(type, event);
+                ctx.executionHandle.emit?.("*", event);
+            }
+            // 3. Emit to global subscribers (for DevTools, telemetry, etc.)
+            for (const subscriber of globalSubscribers) {
+                try {
+                    subscriber(event, ctx);
+                }
+                catch {
+                    // Silently ignore subscriber errors - don't break execution
+                }
+            }
+        }
+    }
+    /**
+     * Subscribe to ALL context events globally.
+     * This is useful for observability tools like DevTools that need to see
+     * all procedure:start/end/error events across all contexts.
+     *
+     * @param handler - Callback that receives every event with its context
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = Context.subscribeGlobal((event, ctx) => {
+     *   if (event.type === 'procedure:start') {
+     *     console.log(`Procedure ${event.payload.name} started`);
+     *   }
+     * });
+     *
+     * // Later, to stop receiving events:
+     * unsubscribe();
+     * ```
+     */
+    static subscribeGlobal(handler) {
+        globalSubscribers.add(handler);
+        return () => {
+            globalSubscribers.delete(handler);
+        };
+    }
+    /**
+     * Check if there are any global subscribers.
+     * Useful for conditional event emission to avoid overhead when no one is listening.
+     */
+    static hasGlobalSubscribers() {
+        return globalSubscribers.size > 0;
+    }
+}
+export class ContextProvider {
+    withContext(context, fn) {
+        return Context.run(Context.create(context), async () => await fn());
+    }
+}
+/**
+ * Symbol used to brand context objects for deterministic detection.
+ * This allows procedures to distinguish context from regular arguments.
+ */
+export const KERNEL_CONTEXT_SYMBOL = Symbol.for("@tentickle/kernel.context");
+/**
+ * Brand a context object with a Symbol for deterministic detection.
+ * This allows procedures to deterministically identify context vs regular args.
+ *
+ * @example
+ * ```typescript
+ * await proc(input, agent, context({ traceId: "123" }));
+ * ```
+ */
+export function context(ctx) {
+    return Context.brand(ctx);
+}
+/**
+ * Check if an object is a branded context (deterministic check via Symbol).
+ * This is 100% reliable - no heuristics needed.
+ */
+export function isKernelContext(obj) {
+    return obj != null && typeof obj === "object" && KERNEL_CONTEXT_SYMBOL in obj;
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAgC,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AA2PjD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAiB,CAAC;AAEvD;;;GAGG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAuD,CAAC;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,OAAO,OAAO;IAClB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,MAAM,CAAC,YAAoD,EAAE;QAClE,OAAO,IAAI,CAAC,KAAK,CAAC;YAChB,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE;YACrD,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE;YACjD,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,EAAE;YAClC,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,IAAI,YAAY,EAAE;YAC1B,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,eAAe,EAAE,SAAS,CAAC,eAAe;YAC1C,0EAA0E;YAC1E,UAAU,EAAE,SAAS,CAAC,UAAU;YAChC,qCAAqC;YACrC,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,aAAa,EAAE,SAAS,CAAC,aAAa;YACtC,iBAAiB,EAAE,SAAS,CAAC,iBAAiB;SAC/C,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,GAA2B;QACtC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,GAAI,GAAW,EAAE,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC;QAC5D,CAAC;QACD,OAAO,GAAoB,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAI,GAA2B,EAAE,EAAoB;QAC7D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAkB,EAAE,EAAE,CAAC,CAAC;IAC9F,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAK,CAAC,YAAoC,EAAE;QACjD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,gDAAgD;YAChD,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC;QACD,sDAAsD;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC;YAChB,GAAG,MAAM;YACT,GAAG,SAAS;SACb,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,IAAI,CAAI,SAAiC,EAAE,EAAoB;QACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,GAAG;QACR,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,YAAY,CAAC,QAAQ,EAAE,CAAC;QAChC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAY;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,GAAG,EAAE,CAAC;YACR,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,IAAY,EAAE,OAAY,EAAE,SAAiB,QAAQ;QAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,GAAG,EAAE,CAAC;YACR,MAAM,KAAK,GAAmB;gBAC5B,IAAI;gBACJ,OAAO;gBACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,MAAM;gBACN,0CAA0C;gBAC1C,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,kDAAkD;gBAClD,WAAW,EAAE,GAAG,CAAC,WAAW;gBAC5B,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;gBACxC,WAAW,EAAE,GAAG,CAAC,YAAY;gBAC7B,IAAI,EAAE,GAAG,CAAC,IAAI;gBACd,4CAA4C;gBAC5C,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE;gBACpB,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ;aAC7B,CAAC;YAEF,oCAAoC;YACpC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC7B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAE5B,qEAAqE;YACrE,IAAI,GAAG,CAAC,eAAe,EAAE,CAAC;gBACxB,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACxC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;YAED,gEAAgE;YAChE,KAAK,MAAM,UAAU,IAAI,iBAAiB,EAAE,CAAC;gBAC3C,IAAI,CAAC;oBACH,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBACzB,CAAC;gBAAC,MAAM,CAAC;oBACP,4DAA4D;gBAC9D,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,eAAe,CAAC,OAA4D;QACjF,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/B,OAAO,GAAG,EAAE;YACV,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,oBAAoB;QACzB,OAAO,iBAAiB,CAAC,IAAI,GAAG,CAAC,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,eAAe;IAC1B,WAAW,CAAI,OAAsB,EAAE,EAAoB;QACzD,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACtE,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAE7E;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CAAC,GAA2B;IACjD,OAAO,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAQ;IACtC,OAAO,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,qBAAqB,IAAI,GAAG,CAAC;AAChF,CAAC"}

package/dist/core/event-buffer.d.ts

@@ -0,0 +1,212 @@
+/**
+ * EventBuffer - Typed event stream with channel-based subscriptions
+ *
+ * A streaming primitive that combines EventEmitter's channel model with:
+ * - **Type-safe channels**: Event `type` property IS the channel name
+ * - **Narrowed handlers**: `on('delta', h)` gives handler the narrowed type
+ * - **Dual consumption**: Multiple consumers see all events independently
+ * - **Replay support**: Late subscribers receive buffered events
+ * - **Async iteration**: `for await (const event of buffer)`
+ *
+ * Events must have a `type` property that acts as the channel discriminator.
+ * This aligns with discriminated union patterns common in TypeScript.
+ *
+ * @module tentickle/core/event-buffer
+ */
+/**
+ * Constraint for events - must have a type discriminator.
+ */
+export type TypedEvent = {
+    type: string;
+};
+/**
+ * Maps event union to a record keyed by type.
+ * Extracts the specific event shape for each type.
+ */
+export type EventMap<T extends TypedEvent> = {
+    [K in T["type"]]: Extract<T, {
+        type: K;
+    }>;
+};
+/**
+ * Handler function for events.
+ */
+export type EventHandler<T> = (event: T) => void;
+/**
+ * Unsubscribe function returned by on/once.
+ */
+export type Unsubscribe = () => void;
+/**
+ * EventBuffer enables typed, channel-based event streaming.
+ *
+ * The event's `type` property IS the channel. Subscribing to 'delta'
+ * means you only receive events where `event.type === 'delta'`.
+ *
+ * @example Basic usage with channels
+ * ```typescript
+ * type StreamEvent =
+ *   | { type: 'delta'; value: string }
+ *   | { type: 'complete'; result: any };
+ *
+ * const buffer = new EventBuffer<StreamEvent>();
+ *
+ * // Subscribe to specific channel - handler gets narrowed type
+ * buffer.on('delta', (event) => {
+ *   console.log(event.value); // TypeScript knows: { type: 'delta', value: string }
+ * });
+ *
+ * // Subscribe to all events
+ * buffer.on((event) => {
+ *   console.log(event); // StreamEvent union
+ * });
+ *
+ * // Emit - type can be first arg (event.type omitted) or in event object
+ * buffer.emit('delta', { value: 'Hello' });
+ * buffer.emit({ type: 'complete', result: 42 });
+ * ```
+ *
+ * @example Late subscriber with replay
+ * ```typescript
+ * buffer.emit('delta', { value: 'first' });
+ * buffer.emit('delta', { value: 'second' });
+ *
+ * // Late subscriber gets all past 'delta' events replayed
+ * buffer.onReplay('delta', (e) => console.log(e.value));
+ * // logs: 'first', 'second'
+ * ```
+ *
+ * @example Async iteration
+ * ```typescript
+ * for await (const event of buffer) {
+ *   if (event.type === 'complete') break;
+ *   console.log(event);
+ * }
+ * ```
+ */
+export declare class EventBuffer<T extends TypedEvent> {
+    private buffer;
+    private subscribers;
+    private waiters;
+    private _closed;
+    private _error;
+    /**
+     * Push an event into the buffer.
+     * Notifies subscribers for this event's type and wildcard subscribers.
+     */
+    push(event: T): void;
+    /**
+     * Emit an event (two-param form: type + event without type property).
+     * @returns true if there were listeners
+     */
+    emit<K extends T["type"]>(eventType: K, event: Omit<EventMap<T>[K], "type">): boolean;
+    /**
+     * Emit an event with wildcard (backwards compat with EventEmitter).
+     * The event must be a full event object with type property.
+     * @returns true if there were listeners
+     */
+    emit(eventType: "*", event: T): boolean;
+    /**
+     * Emit an event (one-param form: full event object with type).
+     * @returns true if there were listeners
+     */
+    emit(event: T): boolean;
+    /**
+     * Subscribe to events of a specific type.
+     * Handler receives the narrowed type for that event.
+     * @returns Unsubscribe function
+     */
+    on<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): Unsubscribe;
+    /**
+     * Subscribe to all events (wildcard).
+     * Pass "*" or no event type for wildcard subscription.
+     * @returns Unsubscribe function
+     */
+    on(eventType: "*", handler: EventHandler<T>): Unsubscribe;
+    on(handler: EventHandler<T>): Unsubscribe;
+    /**
+     * Subscribe for a single event of a specific type.
+     * @returns Unsubscribe function
+     */
+    once<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): Unsubscribe;
+    /**
+     * Subscribe for a single event (any type).
+     * Pass "*" or no event type for wildcard subscription.
+     * @returns Unsubscribe function
+     */
+    once(eventType: "*", handler: EventHandler<T>): Unsubscribe;
+    once(handler: EventHandler<T>): Unsubscribe;
+    /**
+     * Unsubscribe a handler from a specific event type.
+     * @returns true if handler was found and removed
+     */
+    off<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): boolean;
+    /**
+     * Unsubscribe a wildcard handler.
+     * Pass "*" or no event type for wildcard.
+     * @returns true if handler was found and removed
+     */
+    off(eventType: "*", handler: EventHandler<T>): boolean;
+    off(handler: EventHandler<T>): boolean;
+    /**
+     * Subscribe to a specific event type and replay all buffered events of that type.
+     * @returns Unsubscribe function
+     */
+    onReplay<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): Unsubscribe;
+    /**
+     * Subscribe to all events and replay entire buffer.
+     * @returns Unsubscribe function
+     */
+    onReplay(handler: EventHandler<T>): Unsubscribe;
+    private addSubscriber;
+    private removeSubscriber;
+    /**
+     * Close the buffer (no more events).
+     * Completes all async iterators gracefully.
+     */
+    close(): void;
+    /**
+     * Close with an error.
+     * All waiting iterators will throw this error.
+     */
+    error(err: Error): void;
+    /** Whether the buffer is closed. */
+    get closed(): boolean;
+    /** Error that closed the buffer (if any). */
+    get errorValue(): Error | null;
+    /** Number of buffered events. */
+    get length(): number;
+    /** Total number of active subscribers across all channels. */
+    get listenerCount(): number;
+    private getTotalListenerCount;
+    /** Get listener count for a specific event type. */
+    getListenerCount<K extends T["type"]>(eventType: K): number;
+    /** Get wildcard listener count. */
+    getListenerCount(): number;
+    /** Get all buffered events (readonly). */
+    getBuffer(): readonly T[];
+    /** Get buffered events of a specific type. */
+    getBufferByType<K extends T["type"]>(eventType: K): readonly EventMap<T>[K][];
+    /** Convert buffer to array (copy). */
+    toArray(): T[];
+    /**
+     * Async iterator that replays all events then waits for new ones.
+     *
+     * Multiple iterators can exist simultaneously - each sees all events.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<T, void, unknown>;
+    /**
+     * Create a filtered async iterator for a specific event type.
+     */
+    filter<K extends T["type"]>(eventType: K): AsyncGenerator<EventMap<T>[K], void, unknown>;
+    /** Alias for on() (EventEmitter compatibility) */
+    addListener<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): Unsubscribe;
+    addListener(handler: EventHandler<T>): Unsubscribe;
+    /** Alias for off() (EventEmitter compatibility) */
+    removeListener<K extends T["type"]>(eventType: K, handler: EventHandler<EventMap<T>[K]>): boolean;
+    removeListener(handler: EventHandler<T>): boolean;
+    /** @deprecated Use `on()` instead */
+    subscribe(handler: EventHandler<T>): Unsubscribe;
+    /** @deprecated Use `onReplay()` instead */
+    subscribeWithReplay(handler: EventHandler<T>): Unsubscribe;
+}
+//# sourceMappingURL=event-buffer.d.ts.map

package/dist/core/event-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-buffer.d.ts","sourceRoot":"","sources":["../../src/core/event-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,UAAU,IAAI;KAC1C,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAerC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,WAAW,CAAC,CAAC,SAAS,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,WAAW,CAA6C;IAChE,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAsB;IAMpC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IA4BpB;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,OAAO;IACrF;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO;IACvC;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IA0BvB;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IACzF;;;;OAIG;IACH,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IACzD,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IAezC;;;OAGG;IACH,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAC3F;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IAC3D,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IA0B3C;;;OAGG;IACH,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO;IACtF;;;;OAIG;IACH,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO;IACtD,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO;IActC;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW;IAC/F;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IA0B/C,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,gBAAgB;IAcxB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAWb;;;OAGG;IACH,KAAK,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI;IAevB,oCAAoC;IACpC,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,6CAA6C;IAC7C,IAAI,UAAU,IAAI,KAAK,GAAG,IAAI,CAE7B;IAED,iCAAiC;IACjC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,8DAA8D;IAC9D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,OAAO,CAAC,qBAAqB;IAQ7B,oDAAoD;IACpD,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,MAAM;IAC3D,mCAAmC;IACnC,gBAAgB,IAAI,MAAM;IAM1B,0CAA0C;IAC1C,SAAS,IAAI,SAAS,CAAC,EAAE;IAIzB,8CAA8C;IAC9C,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,SAAS,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE;IAI7E,sCAAsC;IACtC,OAAO,IAAI,CAAC,EAAE;IAQd;;;;OAIG;IACI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;IA+BjE;;OAEG;IACI,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;IAY/F,kDAAkD;IAClD,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAC7B,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACpC,WAAW;IACd,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IAQlD,mDAAmD;IACnD,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO;IACjG,cAAc,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO;IAYjD,qCAAqC;IACrC,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;IAIhD,2CAA2C;IAC3C,mBAAmB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW;CAG3D"}