abxbus 2.5.1 → 2.5.4

package/dist/types/CoreEventBus.d.ts

@@ -0,0 +1,334 @@
+import { RustCoreClient, type CoreMessage } from './CoreClient.js';
+import { BaseEvent } from './BaseEvent.js';
+import type { BaseEventJSON } from './BaseEvent.js';
+import { EventHandler } from './EventHandler.js';
+import type { EventHandlerJSON } from './EventHandler.js';
+import { EventResult } from './EventResult.js';
+import { AsyncLock, HandlerLock, type EventConcurrencyMode, type EventHandlerCompletionMode, type EventHandlerConcurrencyMode } from './LockManager.js';
+import type { EventBusMiddlewareInput } from './EventBusMiddleware.js';
+import { type EventHandlerCallable, type EventPattern, type FilterOptions, type FindOptions } from './types.js';
+export type CoreHandler<T extends BaseEvent = BaseEvent> = EventHandlerCallable<T>;
+export type RustCoreEventBusOptions = {
+    id?: string;
+    core?: RustCoreClient;
+    event_concurrency?: EventConcurrencyMode;
+    event_handler_concurrency?: EventHandlerConcurrencyMode;
+    event_handler_completion?: EventHandlerCompletionMode;
+    event_handler_detect_file_paths?: boolean;
+    event_timeout?: number | null;
+    event_slow_timeout?: number | null;
+    event_handler_timeout?: number | null;
+    event_handler_slow_timeout?: number | null;
+    max_history_size?: number | null;
+    max_history_drop?: boolean;
+    middlewares?: EventBusMiddlewareInput[];
+    background_worker?: boolean;
+};
+export type RustCoreHandlerOptions = {
+    id?: string;
+    handler_name?: string;
+    handler_registered_at?: string;
+    handler_file_path?: string | null;
+    handler_timeout?: number | null;
+    handler_slow_timeout?: number | null;
+    handler_concurrency?: EventHandlerConcurrencyMode | null;
+    handler_completion?: EventHandlerCompletionMode | null;
+    [key: string]: unknown;
+};
+export type RustCoreFilterOptions = {
+    limit?: number | null;
+    [field: string]: unknown;
+};
+export type RustCoreEventBusJSON = {
+    id: string;
+    name: string;
+    max_history_size: number | null;
+    max_history_drop: boolean;
+    event_concurrency: EventConcurrencyMode;
+    event_timeout: number | null;
+    event_slow_timeout: number | null;
+    event_handler_concurrency: EventHandlerConcurrencyMode;
+    event_handler_completion: EventHandlerCompletionMode;
+    event_handler_timeout: number | null;
+    event_handler_slow_timeout: number | null;
+    event_handler_detect_file_paths: boolean;
+    handlers: Record<string, EventHandlerJSON>;
+    handlers_by_key: Record<string, string[]>;
+    event_history: Record<string, BaseEventJSON>;
+    pending_event_queue: string[];
+};
+export declare class CoreEventBusRegistry {
+    private _bus_refs;
+    private _bus_refs_by_id;
+    add(bus: RustCoreEventBus): void;
+    discard(bus: RustCoreEventBus): void;
+    has(bus: RustCoreEventBus): boolean;
+    get size(): number;
+    [Symbol.iterator](): IterableIterator<RustCoreEventBus>;
+    findBusById(bus_id: string): RustCoreEventBus | undefined;
+    findEventById(event_id: string): BaseEvent | null;
+}
+export declare const rustCoreEventBusRegistry: CoreEventBusRegistry;
+export declare class CoreEventHistory implements Iterable<[string, BaseEvent]> {
+    max_history_size: number | null;
+    max_history_drop: boolean;
+    private readonly bus;
+    constructor(bus: RustCoreEventBus, options?: {
+        max_history_size?: number | null;
+        max_history_drop?: boolean;
+    });
+    get size(): number;
+    [Symbol.iterator](): Iterator<[string, BaseEvent]>;
+    entries(): IterableIterator<[string, BaseEvent]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<BaseEvent>;
+    clear(): void;
+    get(event_id: string): BaseEvent | undefined;
+    set(event_id: string, event: BaseEvent): this;
+    has(event_id: string): boolean;
+    delete(event_id: string): boolean;
+    addEvent(event: BaseEvent): void;
+    getEvent(event_id: string): BaseEvent | undefined;
+    removeEvent(event_id: string): boolean;
+    hasEvent(event_id: string): boolean;
+    find(event_pattern: '*', options?: FindOptions<BaseEvent>): Promise<BaseEvent | null>;
+    find(event_pattern: '*', where: (event: BaseEvent) => boolean, options?: FindOptions<BaseEvent>): Promise<BaseEvent | null>;
+    find<T extends BaseEvent>(event_pattern: EventPattern<T>, options?: FindOptions<T>): Promise<T | null>;
+    find<T extends BaseEvent>(event_pattern: EventPattern<T>, where: (event: T) => boolean, options?: FindOptions<T>): Promise<T | null>;
+    filter(event_pattern: '*', options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>;
+    filter(event_pattern: '*', where: (event: BaseEvent) => boolean, options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>;
+    filter<T extends BaseEvent>(event_pattern: EventPattern<T>, options?: FilterOptions<T>): Promise<T[]>;
+    filter<T extends BaseEvent>(event_pattern: EventPattern<T>, where: (event: T) => boolean, options?: FilterOptions<T>): Promise<T[]>;
+}
+export declare class CoreLockFacade {
+    private readonly bus;
+    private paused_count;
+    private pause_waiters;
+    private active_handler_results;
+    readonly bus_event_lock: AsyncLock;
+    constructor(bus: RustCoreEventBus);
+    _getActiveHandlerResultForCurrentAsyncContext(): EventResult | undefined;
+    _getActiveHandlerResults(): EventResult[];
+    _requestRunloopPause(): () => void;
+    _waitUntilRunloopResumed(): Promise<void>;
+    _isPaused(): boolean;
+    _notifyIdleListeners(): void;
+    _isAnyHandlerActive(): boolean;
+    getLockForEvent(event: BaseEvent): AsyncLock | null;
+    waitForIdle(timeout?: number | null): Promise<boolean>;
+    _runWithHandlerLock<T>(event: BaseEvent, default_concurrency: EventHandlerConcurrencyMode, fn: (handler_lock: HandlerLock | null) => Promise<T> | T): Promise<T>;
+    _runWithHandlerDispatchContext<T>(result: EventResult, fn: () => Promise<T> | T): Promise<T>;
+    _runWithEventLock<T>(event: BaseEvent, fn: () => Promise<T> | T, options?: {
+        bypass_event_locks?: boolean;
+        pre_acquired_lock?: AsyncLock | null;
+    }): Promise<T>;
+    clear(): void;
+}
+export declare class RustCoreEventBus {
+    readonly core: RustCoreClient;
+    readonly name: string;
+    readonly id: string;
+    readonly bus_id: string;
+    readonly label: string;
+    readonly event_concurrency: EventConcurrencyMode;
+    readonly event_handler_concurrency: EventHandlerConcurrencyMode;
+    readonly event_handler_completion: EventHandlerCompletionMode;
+    readonly event_handler_detect_file_paths: boolean;
+    readonly event_timeout: number | null;
+    readonly event_slow_timeout: number | null;
+    readonly event_handler_timeout: number | null;
+    readonly event_handler_slow_timeout: number | null;
+    readonly handlers: Map<string, EventHandler>;
+    readonly handlers_by_key: Map<string, string[]>;
+    readonly event_history: CoreEventHistory;
+    readonly locks: CoreLockFacade;
+    all_instances: CoreEventBusRegistry;
+    _lock_for_event_global_serial: AsyncLock;
+    in_flight_event_ids: Set<string>;
+    runloop_running: boolean;
+    private registered;
+    private events;
+    private processing;
+    private processing_tasks;
+    private middlewares;
+    private invocation_by_result_id;
+    private abort_by_invocation_id;
+    private event_types_by_pattern;
+    private event_timeout_causes;
+    private event_completion_waiters;
+    private event_emission_waiters;
+    private invocation_worker;
+    private background_worker_enabled;
+    private foreground_drain_task;
+    private foreground_drain_requested;
+    private serial_route_pause_releases;
+    private completed_event_refs;
+    private closed;
+    private readonly owns_shared_core;
+    private registered_max_history_size;
+    private registered_max_history_drop;
+    constructor(name?: string, options?: RustCoreEventBusOptions);
+    get pending_event_queue(): BaseEvent[];
+    get find_waiters(): Set<(event: BaseEvent) => void>;
+    set pending_event_queue(events: BaseEvent[]);
+    toString(): string;
+    defaultsRecord(): Record<string, unknown>;
+    private busRecord;
+    start(): void;
+    private syncBusHistoryPolicy;
+    on<T extends BaseEvent>(event_type: EventPattern<T>, handler: CoreHandler<T>, options?: RustCoreHandlerOptions): EventHandler;
+    on(event_type: '*', handler: CoreHandler, options?: RustCoreHandlerOptions): EventHandler;
+    off<T extends BaseEvent>(event_type: EventPattern<T> | '*', handler?: CoreHandler<T> | string | EventHandler): void;
+    emit<T extends BaseEvent>(event: T): T;
+    emit(event: Record<string, unknown>): Promise<CoreMessage>;
+    private scheduleForegroundDrain;
+    _onRunloopResumed(): void;
+    private drainForegroundCore;
+    private processAvailableCoreMessages;
+    private coreEventRecordForEmit;
+    private coreForwardControlOptions;
+    dispatch<T extends BaseEvent>(event: T): T;
+    onEventChange(_event: BaseEvent, _status: 'pending' | 'started' | 'completed'): Promise<void>;
+    onEventResultChange(_event: BaseEvent, _result: EventResult, _status: 'pending' | 'started' | 'completed'): Promise<void>;
+    hasMiddlewareHooks(): boolean;
+    hasEventChangeHooks(): boolean;
+    hasEventResultHooks(): boolean;
+    _notifyEventChange(event: BaseEvent, status: 'pending' | 'started' | 'completed'): void;
+    _notifyEventResultChange(event: BaseEvent, result: EventResult, status: 'pending' | 'started' | 'completed'): void;
+    findEventById(event_id: string): BaseEvent | null;
+    findLocalEventById(event_id: string): BaseEvent | undefined;
+    rememberEvent(event_id: string, event: BaseEvent): void;
+    rememberLiveEvent(event_id: string, event: BaseEvent): void;
+    forgetEvent(event_id: string): void;
+    localEvents(): IterableIterator<BaseEvent>;
+    importEventsToCore(events: BaseEvent[], pending_events?: BaseEvent[]): void;
+    historyRecords(event_pattern?: string, limit?: number | null): Record<string, unknown>[];
+    historyEventIds(event_pattern?: string, limit?: number | null, statuses?: string[] | null): string[];
+    coreRecordBelongsToThisBus(record: Record<string, unknown>): boolean;
+    activeHandlerResult(): EventResult | null;
+    _getEventProxyScopedToThisBus<T extends BaseEvent>(event: T, _handler_result?: EventResult): T;
+    _hasProcessedEvent(event: BaseEvent): boolean;
+    _getHandlersForEvent(event: BaseEvent): EventHandler[];
+    private ensurePendingLocalResults;
+    _processEventImmediately<T extends BaseEvent>(event: T, _handler_result?: EventResult): Promise<T>;
+    private findActiveInvocationForQueueJump;
+    private waitForLocalCompletionPush;
+    private waitForLocalCompletionOrProcessingDrain;
+    _waitForEventCompletedInQueueOrder<T extends BaseEvent>(event: T): Promise<T>;
+    private eventIsOwnedByActiveHandler;
+    private findParentInvocationForEvent;
+    private findBusForInvocation;
+    processUntilEventCompleted(event_id: string, initial_messages?: CoreMessage[] | null): Promise<BaseEvent>;
+    private waitForCoreCompletedEvent;
+    runUntilEventCompleted(event_id: string): Promise<BaseEvent>;
+    _syncEventRuntimeOptions(event: BaseEvent): void;
+    waitUntilIdle(timeout?: number | null): Promise<boolean>;
+    isIdle(): boolean;
+    isIdleAndQueueEmpty(): boolean;
+    removeEventFromPendingQueue(_event: BaseEvent): number;
+    isEventInFlightOrQueued(event_id: string): boolean;
+    removeEventFromHistory(event_id: string): boolean;
+    destroy(options?: number | {
+        timeout?: number | null;
+        clear?: boolean;
+    }): Promise<void>;
+    eventIsChildOf(child_event: BaseEvent, parent_event: BaseEvent): boolean;
+    eventIsParentOf(parent_event: BaseEvent, child_event: BaseEvent): boolean;
+    logTree(): string;
+    private applyAndRunMessagesUntilEventCompleted;
+    private runInvocationMessagesInCoreRouteOrder;
+    private completedSnapshotOrEvent;
+    private releaseCompletedLocalEvent;
+    private trackLocalEventUntilCoreEvictsIt;
+    collectEvictedCompletedEventRefs(visible_event_ids?: Set<string> | null): void;
+    private pendingQueueEventsFromCore;
+    private refreshPendingQueueFromCore;
+    private refreshKnownEventsFromCore;
+    private applyCoreSnapshotToEvent;
+    find<T extends BaseEvent>(event_type: EventPattern<T> | '*', where_or_options?: ((event: T) => boolean) | FindOptions<T>, maybe_options?: FindOptions<T>): Promise<T | null>;
+    filter<T extends BaseEvent>(event_type: EventPattern<T> | '*', where_or_options?: ((event: T) => boolean) | FilterOptions<T>, maybe_options?: FilterOptions<T>): Promise<T[]>;
+    disconnect(): void;
+    close(): void;
+    stop(): void;
+    scheduleMicrotask(fn: () => void): void;
+    toJSON(): RustCoreEventBusJSON;
+    eventFromCoreRecord<T extends BaseEvent>(event_type: EventPattern<T> | '*', record: Record<string, unknown>): BaseEvent;
+    private isStaleInvocationOutcomeError;
+    private eventSnapshotMessageForInvocation;
+    private completeHandlerOrSnapshot;
+    private completeHandlerNoPatchesOrSnapshot;
+    private canUsePatchlessCompletedOutcome;
+    private errorHandlerOrSnapshot;
+    private activeCoreOutcomeBatch;
+    private runWithCoreOutcomeBatch;
+    private runWithoutCoreOutcomeBatch;
+    private localOutcomePatchMessages;
+    private commitInvocationOutcomeMessages;
+    private invocationCanUseBatchedOutcome;
+    private invocationUsesFirstCompletion;
+    private eventForInvocation;
+    private runInvocationOutcome;
+    private runInvocation;
+    private startForegroundCoreSignalTimer;
+    private applyExpiredEventTimeout;
+    private startForegroundEventTimeoutTimer;
+    private startedAtForInvocation;
+    private eventTimeoutForInvocation;
+    private startForegroundEventSlowWarningTimer;
+    private eventSlowTimeoutForInvocation;
+    private abortResultForEventTimeout;
+    private invocationAbortError;
+    private eventTimeoutIpcGraceSeconds;
+    private processAvailableAfterHandlerOutcome;
+    private releaseSerialRoutePausesForInvocation;
+    private applyResultSnapshot;
+    private retargetErrorResult;
+    private orderedResultRecords;
+    private childIdsFromResultRecord;
+    private attachResultChildren;
+    private normalizeResultError;
+    private restoreCoreError;
+    private restoreGenericError;
+    private publicCoreErrorMessage;
+    private causeForCancellation;
+    private parentTimeoutEventIdFromMessage;
+    private eventTimeoutCause;
+    private timeoutSecondsForCoreError;
+    private eventTimeoutSecondsForResult;
+    private resolveTimeoutOverride;
+    private positiveTimeoutFromUnknown;
+    private numberFromUnknown;
+    private timestampMs;
+    private timestampBefore;
+    private warnSlowEvent;
+    private warnSlowResult;
+    runWithActiveHandlerResult<T>(result: EventResult, fn: () => T): T;
+    private startWorker;
+    private stopWorker;
+    private handleWorkerMessages;
+    private runAndApplyInvocationMessages;
+    private runInvocationMessages;
+    private resolveEventCompletionWaiters;
+    private notifyEventEmissionWaiters;
+    private waitForLocalEventEmission;
+    private waitForEventCompleted;
+    private localBusesForCoreSession;
+    private busForInvocation;
+    private applyCoreMessageToLocalBuses;
+    private targetBusesForCoreMessage;
+    private applyCoreMessage;
+    private applyCoreMessageFromSharedCursor;
+    private patchBelongsToThisBus;
+    private localResultIdExists;
+    private applyCoreMessageUnchecked;
+    private applyResultRecord;
+    private cancelFirstModeLosersForCompletedEvent;
+    private _runMiddlewareHook;
+    private _onBusHandlersChange;
+    private waitForFutureMatch;
+    private findCoreRecordCreatedAfter;
+    private waitForEventEmittedCancellable;
+}
+export declare const stableCoreBusId: (bus_name: string) => string;
+export declare const uniqueCoreBusId: () => string;
+export declare const defaultCoreBusId: (bus_name: string, registry: CoreEventBusRegistry) => string;

package/dist/types/base_event.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import { EventBus } from './event_bus.js';
+import { EventResult } from './event_result.js';
+import { EventHandler } from './event_handler.js';
+import type { EventConcurrencyMode, EventHandlerConcurrencyMode, EventHandlerCompletionMode, Deferred } from './lock_manager.js';
+import { AsyncLock } from './lock_manager.js';
+import type { EventHandlerCallable, EventResultType } from './types.js';
+export declare const BaseEventSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    event_created_at: z.ZodString;
+    event_type: z.ZodString;
+    event_version: z.ZodDefault<z.ZodString>;
+    event_timeout: z.ZodNullable<z.ZodNumber>;
+    event_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    event_handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    event_handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    event_blocks_parent_completion: z.ZodOptional<z.ZodBoolean>;
+    event_parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    event_result_type: z.ZodOptional<z.ZodUnknown>;
+    event_emitted_by_handler_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_pending_bus_count: z.ZodOptional<z.ZodNumber>;
+    event_status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        started: "started";
+        completed: "completed";
+    }>>;
+    event_started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_results: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    event_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        "global-serial": "global-serial";
+        "bus-serial": "bus-serial";
+        parallel: "parallel";
+    }>>>;
+    event_handler_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        parallel: "parallel";
+        serial: "serial";
+    }>>>;
+    event_handler_completion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        all: "all";
+        first: "first";
+    }>>>;
+}, z.core.$loose>;
+export type BaseEventData = z.infer<typeof BaseEventSchema>;
+export type BaseEventJSON = BaseEventData & Record<string, unknown>;
+type BaseEventFields = Pick<BaseEventData, 'event_id' | 'event_created_at' | 'event_type' | 'event_version' | 'event_timeout' | 'event_slow_timeout' | 'event_handler_timeout' | 'event_handler_slow_timeout' | 'event_blocks_parent_completion' | 'event_parent_id' | 'event_path' | 'event_result_type' | 'event_emitted_by_handler_id' | 'event_pending_bus_count' | 'event_status' | 'event_started_at' | 'event_completed_at' | 'event_results' | 'event_concurrency' | 'event_handler_concurrency' | 'event_handler_completion'>;
+export type BaseEventInit<TFields extends Record<string, unknown>> = TFields & Partial<BaseEventFields>;
+type BaseEventSchemaShape = typeof BaseEventSchema.shape;
+export type EventSchema<TShape extends z.ZodRawShape> = z.ZodObject<BaseEventSchemaShape & TShape>;
+type EventPayload<TShape extends z.ZodRawShape> = TShape extends Record<string, never> ? {} : z.infer<z.ZodObject<TShape>>;
+type EventInput<TShape extends z.ZodRawShape> = z.input<EventSchema<TShape>>;
+export type EventInit<TShape extends z.ZodRawShape> = Omit<EventInput<TShape>, keyof BaseEventFields> & Partial<BaseEventFields>;
+type EventWithResultSchema<TResult> = BaseEvent & {
+    __event_result_type__?: TResult;
+};
+type ResultTypeFromEventResultTypeInput<TInput> = TInput extends z.ZodTypeAny ? z.infer<TInput> : TInput extends StringConstructor ? string : TInput extends NumberConstructor ? number : TInput extends BooleanConstructor ? boolean : TInput extends ArrayConstructor ? unknown[] : TInput extends ObjectConstructor ? Record<string, unknown> : unknown;
+type ResultSchemaFromShape<TShape> = TShape extends {
+    event_result_type: infer S;
+} ? ResultTypeFromEventResultTypeInput<S> : unknown;
+type EventResultsListInclude<TEvent extends BaseEvent> = (result: EventResultType<TEvent> | undefined, event_result: EventResult<TEvent>) => boolean;
+type EventResultsListOptions<TEvent extends BaseEvent> = {
+    timeout?: number | null;
+    include?: EventResultsListInclude<TEvent>;
+    raise_if_any?: boolean;
+    raise_if_none?: boolean;
+};
+type EventDoneOptions = {
+    raise_if_any?: boolean;
+};
+type EventResultUpdateOptions<TEvent extends BaseEvent> = {
+    eventbus?: EventBus;
+    status?: 'pending' | 'started' | 'completed' | 'error';
+    result?: EventResultType<TEvent> | BaseEvent | undefined;
+    error?: unknown;
+};
+export type EventFactory<TShape extends z.ZodRawShape, TResult = unknown> = {
+    (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>;
+    new (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>;
+    schema: EventSchema<TShape>;
+    class?: new (data: EventInit<TShape>) => EventWithResultSchema<TResult> & EventPayload<TShape>;
+    event_type?: string;
+    event_version?: string;
+    event_result_type?: z.ZodTypeAny;
+    fromJSON?: (data: unknown) => EventWithResultSchema<TResult> & EventPayload<TShape>;
+};
+type ZodShapeFrom<TShape extends Record<string, unknown>> = {
+    [K in keyof TShape as K extends 'event_result_type' ? never : TShape[K] extends z.ZodTypeAny ? K : never]: Extract<TShape[K], z.ZodTypeAny>;
+};
+export declare class BaseEvent {
+    event_id: string;
+    event_created_at: string;
+    event_type: string;
+    event_version: string;
+    event_timeout: number | null;
+    event_slow_timeout?: number | null;
+    event_handler_timeout?: number | null;
+    event_handler_slow_timeout?: number | null;
+    event_blocks_parent_completion: boolean;
+    event_parent_id: string | null;
+    event_path: string[];
+    event_result_type?: z.ZodTypeAny;
+    event_results: Map<string, EventResult<this>>;
+    event_emitted_by_handler_id: string | null;
+    event_pending_bus_count: number;
+    event_status: 'pending' | 'started' | 'completed';
+    event_started_at: string | null;
+    event_completed_at: string | null;
+    event_concurrency?: EventConcurrencyMode | null;
+    event_handler_concurrency?: EventHandlerConcurrencyMode | null;
+    event_handler_completion?: EventHandlerCompletionMode | null;
+    static event_type?: string;
+    static event_version: string;
+    static schema: z.ZodObject<{
+        event_id: z.ZodString;
+        event_created_at: z.ZodString;
+        event_type: z.ZodString;
+        event_version: z.ZodDefault<z.ZodString>;
+        event_timeout: z.ZodNullable<z.ZodNumber>;
+        event_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        event_handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        event_handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        event_blocks_parent_completion: z.ZodOptional<z.ZodBoolean>;
+        event_parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        event_result_type: z.ZodOptional<z.ZodUnknown>;
+        event_emitted_by_handler_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_pending_bus_count: z.ZodOptional<z.ZodNumber>;
+        event_status: z.ZodOptional<z.ZodEnum<{
+            pending: "pending";
+            started: "started";
+            completed: "completed";
+        }>>;
+        event_started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_results: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        event_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            "global-serial": "global-serial";
+            "bus-serial": "bus-serial";
+            parallel: "parallel";
+        }>>>;
+        event_handler_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            parallel: "parallel";
+            serial: "serial";
+        }>>>;
+        event_handler_completion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            all: "all";
+            first: "first";
+        }>>>;
+    }, z.core.$loose>;
+    event_bus?: EventBus;
+    _event_original?: BaseEvent;
+    _event_dispatch_context?: unknown | null;
+    _event_completed_signal: Deferred<this> | null;
+    _lock_for_event_handler: AsyncLock | null;
+    constructor(data?: BaseEventInit<Record<string, unknown>>);
+    toString(): string;
+    static extend<TShape extends z.ZodRawShape>(event_type: string, shape?: TShape): EventFactory<TShape, ResultSchemaFromShape<TShape>>;
+    static extend<TShape extends Record<string, unknown>>(event_type: string, shape?: TShape): EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>>;
+    static fromJSON<T extends typeof BaseEvent>(this: T, data: unknown): InstanceType<T>;
+    static toJSONArray(events: Iterable<BaseEvent>): BaseEventJSON[];
+    static fromJSONArray(data: unknown): BaseEvent[];
+    toJSON(): BaseEventJSON;
+    _createSlowEventWarningTimer(): ReturnType<typeof setTimeout> | null;
+    eventResultUpdate(handler: EventHandler | EventHandlerCallable<this>, options?: EventResultUpdateOptions<this>): EventResult<this>;
+    _createPendingHandlerResults(bus: EventBus): Array<{
+        handler: EventHandler;
+        result: EventResult;
+    }>;
+    private _collectPendingResults;
+    private _isFirstModeWinningResult;
+    private _markFirstModeWinnerIfNeeded;
+    private _runHandlerWithLock;
+    _runHandlers(pending_entries?: Array<{
+        handler: EventHandler;
+        result: EventResult;
+    }>): Promise<void>;
+    _getHandlerLock(default_concurrency?: EventHandlerConcurrencyMode): AsyncLock | null;
+    _setHandlerLock(lock: AsyncLock | null): void;
+    _getDispatchContext(): unknown | null | undefined;
+    _setDispatchContext(dispatch_context: unknown | null | undefined): void;
+    get event_parent(): BaseEvent | undefined;
+    get event_children(): BaseEvent[];
+    get event_descendants(): BaseEvent[];
+    emit<T extends BaseEvent>(event: T): T;
+    _cancelPendingChildProcessing(reason: unknown): void;
+    _markRemainingFirstModeResultCancelled(winner: EventResult): void;
+    _markCancelled(cause: Error): void;
+    _notifyEventParentsOfCompletion(): void;
+    done(options?: EventDoneOptions): Promise<this>;
+    first(): Promise<EventResultType<this> | undefined>;
+    eventResultsList(include: EventResultsListInclude<this>, options?: EventResultsListOptions<this>): Promise<Array<EventResultType<this> | undefined>>;
+    eventResultsList(options?: EventResultsListOptions<this>): Promise<Array<EventResultType<this> | undefined>>;
+    eventCompleted(): Promise<this>;
+    _markBlocksParentCompletionIfAwaitedFromEmittingHandler(): void;
+    _markPending(): this;
+    eventReset(): this;
+    _markStarted(started_at?: string | null, notify_hook?: boolean): void;
+    _markCompleted(force?: boolean, notify_parents?: boolean): void;
+    private dropFromZeroHistoryBuses;
+    get event_errors(): unknown[];
+    private _isFirstModeControlError;
+    _firstProcessingError(options?: {
+        ignore_first_mode_control_errors?: boolean;
+    }): unknown | undefined;
+    get event_result(): EventResultType<this> | undefined;
+    _areAllChildrenComplete(visited?: Set<string>): boolean;
+    private _notifyDoneListeners;
+    _gc(): void;
+}
+export {};

package/dist/types/bridge_jsonl.d.ts

@@ -0,0 +1,26 @@
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class JSONLEventBridge {
+    readonly path: string;
+    readonly poll_interval: number;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private byte_offset;
+    private pending_line;
+    private listener_task;
+    constructor(path: string, poll_interval?: number, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private listenLoop;
+    private pollNewLines;
+    private dispatchInboundPayload;
+    private readAppended;
+    private dirname;
+    private loadFs;
+}

package/dist/types/bridge_nats.d.ts

@@ -0,0 +1,20 @@
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class NATSEventBridge {
+    readonly server: string;
+    readonly subject: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private nc;
+    private sub_task;
+    constructor(server: string, subject: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchInboundPayload;
+}

package/dist/types/bridge_postgres.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PostgreSQL LISTEN/NOTIFY + flat-table bridge for forwarding events.
+ */
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class PostgresEventBridge {
+    readonly table_url: string;
+    readonly dsn: string;
+    readonly table: string;
+    readonly channel: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private client;
+    private table_columns;
+    private notification_handler;
+    constructor(table_url: string, channel?: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchByEventId;
+    private dispatchInboundPayload;
+    private ensureTableExists;
+    private ensureBaseIndexes;
+    private refreshColumnCache;
+    private ensureColumns;
+}

package/dist/types/bridge_redis.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Redis pub/sub bridge for forwarding events between runtimes.
+ *
+ * Usage:
+ *   // channel from URL path
+ *   const bridge = new RedisEventBridge('redis://user:pass@localhost:6379/1/my_channel')
+ *
+ *   // explicit channel override
+ *   const bridge2 = new RedisEventBridge('redis://user:pass@localhost:6379/1', 'my_channel')
+ *
+ * URL format:
+ *   redis://user:pass@host:6379/<db>/<optional_channel>
+ */
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class RedisEventBridge {
+    readonly url: string;
+    readonly channel: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private start_promise;
+    private redis_pub;
+    private redis_sub;
+    constructor(redis_url: string, channel?: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchInboundPayload;
+}