actor-ts 0.9.0

package/dist/CoordinatedShutdown.js

@@ -0,0 +1,252 @@
+import { extensionId } from './Extension.js';
+/**
+ * Structured reason passed to every shutdown task so that they can behave
+ * differently depending on who triggered the shutdown (SIGTERM vs. cluster
+ * leave vs. hot-reload vs. …).
+ */
+export class Reason {
+    toString() { return this.name; }
+}
+export class UnknownReason extends Reason {
+    name = 'UnknownReason';
+    static instance = new UnknownReason();
+}
+export class ActorSystemTerminateReason extends Reason {
+    name = 'ActorSystemTerminateReason';
+    static instance = new ActorSystemTerminateReason();
+}
+export class ClusterLeavingReason extends Reason {
+    name = 'ClusterLeavingReason';
+    static instance = new ClusterLeavingReason();
+}
+export class ClusterDowningReason extends Reason {
+    name = 'ClusterDowningReason';
+    static instance = new ClusterDowningReason();
+}
+/** Received SIGTERM / SIGINT from the process. */
+export class ProcessTerminateReason extends Reason {
+    signal;
+    constructor(signal) {
+        super();
+        this.signal = signal;
+    }
+    name = 'ProcessTerminateReason';
+    toString() { return `ProcessTerminateReason(${this.signal})`; }
+}
+/** Canonical phase names, run in order from top to bottom. */
+export const Phases = {
+    BeforeServiceUnbind: 'before-service-unbind',
+    ServiceUnbind: 'service-unbind',
+    ServiceRequestsDone: 'service-requests-done',
+    ServiceStop: 'service-stop',
+    BeforeClusterShutdown: 'before-cluster-shutdown',
+    ClusterShardingShutdownRegion: 'cluster-sharding-shutdown-region',
+    ClusterLeave: 'cluster-leave',
+    ClusterExiting: 'cluster-exiting',
+    ClusterExitingDone: 'cluster-exiting-done',
+    ClusterShutdown: 'cluster-shutdown',
+    BeforeActorSystemTerminate: 'before-actor-system-terminate',
+    ActorSystemTerminate: 'actor-system-terminate',
+};
+/**
+ * Lifecycle coordinator that runs registered tasks in well-known phases.
+ * Ordinary application code calls `addTask(phase, name, task)`; the runtime
+ * guarantees task order across phases and bounded parallelism within a
+ * phase.  Task failures are logged and do NOT by default abort the rest of
+ * the pipeline.
+ */
+export class CoordinatedShutdown {
+    system;
+    phases = new Map();
+    tasks = new Map();
+    _running = false;
+    _completed = false;
+    _runPromise = null;
+    _processHooksInstalled = false;
+    _processHookSignals = [];
+    /**
+     * Default per-phase timeout in ms.  Can be changed globally or per-phase
+     * via `setPhaseTimeout`.  5 seconds is a reasonable balance between
+     * letting slow tasks finish and not blocking shutdown indefinitely.
+     */
+    defaultPhaseTimeoutMs = 5_000;
+    constructor(system) {
+        this.system = system;
+        // Seed the 12 canonical phases linearly — each depends on the previous.
+        const order = [
+            Phases.BeforeServiceUnbind,
+            Phases.ServiceUnbind,
+            Phases.ServiceRequestsDone,
+            Phases.ServiceStop,
+            Phases.BeforeClusterShutdown,
+            Phases.ClusterShardingShutdownRegion,
+            Phases.ClusterLeave,
+            Phases.ClusterExiting,
+            Phases.ClusterExitingDone,
+            Phases.ClusterShutdown,
+            Phases.BeforeActorSystemTerminate,
+            Phases.ActorSystemTerminate,
+        ];
+        for (let i = 0; i < order.length; i++) {
+            this.phases.set(order[i], {
+                name: order[i],
+                timeoutMs: this.defaultPhaseTimeoutMs,
+                dependsOn: i === 0 ? [] : [order[i - 1]],
+                recover: true,
+            });
+        }
+        // Built-in terminator in the final phase.
+        this.addTask(Phases.ActorSystemTerminate, 'terminate-actor-system', async () => {
+            if (!this.system.isTerminated)
+                await this.system.terminate();
+        });
+    }
+    /* ----------------------------- Public API ----------------------------- */
+    /** Register a task to run during the given phase.  Task names must be unique within a phase. */
+    addTask(phase, name, task) {
+        if (!this.phases.has(phase)) {
+            throw new Error(`CoordinatedShutdown: unknown phase "${phase}"`);
+        }
+        const list = this.tasks.get(phase) ?? [];
+        if (list.some(t => t.name === name)) {
+            throw new Error(`CoordinatedShutdown: task "${name}" already registered in phase "${phase}"`);
+        }
+        list.push({ name, task });
+        this.tasks.set(phase, list);
+    }
+    /** Add a custom phase.  `dependsOn` tells the coordinator where in the order it sits. */
+    addPhase(def) {
+        if (this.phases.has(def.name)) {
+            throw new Error(`CoordinatedShutdown: phase "${def.name}" already exists`);
+        }
+        for (const dep of def.dependsOn) {
+            if (!this.phases.has(dep)) {
+                throw new Error(`CoordinatedShutdown: phase "${def.name}" depends on unknown "${dep}"`);
+            }
+        }
+        this.phases.set(def.name, def);
+    }
+    /** Override the timeout for a phase.  Uses `defaultPhaseTimeoutMs` by default. */
+    setPhaseTimeout(phase, timeoutMs) {
+        const p = this.phases.get(phase);
+        if (!p)
+            throw new Error(`Unknown phase: ${phase}`);
+        this.phases.set(phase, { ...p, timeoutMs });
+    }
+    /** True once `run()` has been kicked off. */
+    get isRunning() { return this._running; }
+    /** True once `run()` has completed (successful or not). */
+    get isComplete() { return this._completed; }
+    /**
+     * Run the pipeline.  Safe to call from multiple sites — subsequent calls
+     * return the same in-flight promise.
+     */
+    run(reason = UnknownReason.instance) {
+        if (this._runPromise)
+            return this._runPromise;
+        this._runPromise = this._run(reason);
+        return this._runPromise;
+    }
+    /**
+     * Install SIGTERM / SIGINT handlers that call `run(ProcessTerminateReason)`.
+     * Calling twice is harmless.  Uninstall via `removeProcessHooks`.
+     */
+    installProcessHooks(signals = ['SIGTERM', 'SIGINT']) {
+        if (this._processHooksInstalled)
+            return;
+        if (typeof process === 'undefined' || typeof process.on !== 'function')
+            return;
+        for (const sig of signals) {
+            const handler = () => {
+                void this.run(new ProcessTerminateReason(sig));
+            };
+            process.on(sig, handler);
+            this._processHookSignals.push(sig);
+        }
+        this._processHooksInstalled = true;
+    }
+    removeProcessHooks() {
+        if (!this._processHooksInstalled)
+            return;
+        if (typeof process === 'undefined')
+            return;
+        for (const sig of this._processHookSignals) {
+            process.removeAllListeners(sig);
+        }
+        this._processHooksInstalled = false;
+        this._processHookSignals = [];
+    }
+    /* ------------------------------- Internal ------------------------------ */
+    async _run(reason) {
+        this._running = true;
+        const order = this.topologicalOrder();
+        for (const phase of order) {
+            await this.runPhase(phase, reason);
+        }
+        this._completed = true;
+    }
+    async runPhase(phase, reason) {
+        const def = this.phases.get(phase);
+        const tasks = this.tasks.get(phase) ?? [];
+        if (tasks.length === 0)
+            return;
+        const promises = tasks.map(t => this.runOneTask(t, def, reason));
+        if (def.recover) {
+            await Promise.all(promises.map(p => p.catch(() => { })));
+        }
+        else {
+            await Promise.all(promises);
+        }
+    }
+    async runOneTask(t, def, reason) {
+        let timeoutHandle = null;
+        const timeout = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => reject(new Error(`Shutdown task "${t.name}" in phase "${def.name}" timed out after ${def.timeoutMs}ms`)), def.timeoutMs);
+            timeoutHandle.unref?.();
+        });
+        try {
+            await Promise.race([Promise.resolve(t.task(reason)), timeout]);
+        }
+        catch (e) {
+            this.system.log.warn(`[shutdown] task "${t.name}" in phase "${def.name}" failed: ${e.message}`);
+            if (!def.recover)
+                throw e;
+        }
+        finally {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+        }
+    }
+    /** Kahn-style topological sort over the phase DAG. */
+    topologicalOrder() {
+        const remaining = new Map();
+        for (const [name, def] of this.phases) {
+            remaining.set(name, [...def.dependsOn]);
+        }
+        const out = [];
+        while (remaining.size > 0) {
+            const ready = Array.from(remaining.entries())
+                .filter(([, deps]) => deps.length === 0)
+                .map(([name]) => name)
+                .sort(); // deterministic tiebreaker
+            if (ready.length === 0) {
+                throw new Error(`CoordinatedShutdown: cycle in phase dependencies: ${Array.from(remaining.keys()).join(', ')}`);
+            }
+            for (const name of ready) {
+                out.push(name);
+                remaining.delete(name);
+            }
+            for (const [, deps] of remaining) {
+                for (const done of ready) {
+                    const idx = deps.indexOf(done);
+                    if (idx >= 0)
+                        deps.splice(idx, 1);
+                }
+            }
+        }
+        return out;
+    }
+}
+/** ExtensionId — use via `system.extension(CoordinatedShutdownId)`. */
+export const CoordinatedShutdownId = extensionId('CoordinatedShutdown', (system) => new CoordinatedShutdown(system));
+//# sourceMappingURL=CoordinatedShutdown.js.map

package/dist/CoordinatedShutdown.js.map

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

package/dist/Dispatcher.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A Dispatcher schedules the execution of actor message-processing units.
+ * In a single-threaded JS runtime we pick between the microtask queue and
+ * setImmediate to balance throughput against fairness with I/O.
+ */
+export interface Dispatcher {
+    readonly id: string;
+    /** Schedule a unit of work to be executed asynchronously. */
+    execute(fn: () => void | Promise<void>): void;
+}
+/**
+ * Runs work on the microtask queue. Fastest, but can starve I/O and timers
+ * under sustained actor load because microtasks always run before macrotasks.
+ */
+export declare class MicrotaskDispatcher implements Dispatcher {
+    readonly id = "microtask-dispatcher";
+    execute(fn: () => void | Promise<void>): void;
+}
+/**
+ * Runs work via setImmediate (or setTimeout(0) in browsers). Lets I/O and
+ * timers interleave between messages, so it is the default.
+ */
+export declare class ImmediateDispatcher implements Dispatcher {
+    readonly id = "immediate-dispatcher";
+    execute(fn: () => void | Promise<void>): void;
+}
+/**
+ * Processes up to `throughput` queued units synchronously before yielding.
+ * Useful when actors exchange many small messages and you want less
+ * scheduling overhead.  Be aware that you can starve the event loop if
+ * throughput is set high.
+ */
+export declare class ThroughputDispatcher implements Dispatcher {
+    readonly throughput: number;
+    readonly id: string;
+    private queue;
+    private scheduled;
+    constructor(throughput?: number, id?: string);
+    execute(fn: () => void | Promise<void>): void;
+    private drain;
+}
+export declare const Dispatchers: {
+    Immediate: () => ImmediateDispatcher;
+    Microtask: () => MicrotaskDispatcher;
+    Throughput: (throughput?: number) => ThroughputDispatcher;
+};
+//# sourceMappingURL=Dispatcher.d.ts.map

package/dist/Dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.d.ts","sourceRoot":"","sources":["../src/Dispatcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/C;AAeD;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IACpD,QAAQ,CAAC,EAAE,0BAA0B;IACrC,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CAG9C;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IACpD,QAAQ,CAAC,EAAE,0BAA0B;IACrC,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CAO9C;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,UAAU;aAKzB,UAAU,EAAE,MAAM;IAJ9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,KAAK,CAAyC;IACtD,OAAO,CAAC,SAAS,CAAS;gBAEE,UAAU,GAAE,MAAW,EAAE,EAAE,GAAE,MAAgC;IAIzF,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAY7C,OAAO,CAAC,KAAK;CAiBd;AAED,eAAO,MAAM,WAAW;;;8BAGG,MAAM;CAChC,CAAC"}

package/dist/Dispatcher.js

@@ -0,0 +1,90 @@
+function runSafely(fn) {
+    try {
+        const result = fn();
+        if (result && typeof result.catch === 'function') {
+            result.catch((err) => {
+                console.error('[actor-ts] unhandled dispatcher error:', err);
+            });
+        }
+    }
+    catch (err) {
+        console.error('[actor-ts] unhandled dispatcher error:', err);
+    }
+}
+/**
+ * Runs work on the microtask queue. Fastest, but can starve I/O and timers
+ * under sustained actor load because microtasks always run before macrotasks.
+ */
+export class MicrotaskDispatcher {
+    id = 'microtask-dispatcher';
+    execute(fn) {
+        queueMicrotask(() => runSafely(fn));
+    }
+}
+/**
+ * Runs work via setImmediate (or setTimeout(0) in browsers). Lets I/O and
+ * timers interleave between messages, so it is the default.
+ */
+export class ImmediateDispatcher {
+    id = 'immediate-dispatcher';
+    execute(fn) {
+        if (typeof setImmediate === 'function') {
+            setImmediate(() => runSafely(fn));
+        }
+        else {
+            setTimeout(() => runSafely(fn), 0);
+        }
+    }
+}
+/**
+ * Processes up to `throughput` queued units synchronously before yielding.
+ * Useful when actors exchange many small messages and you want less
+ * scheduling overhead.  Be aware that you can starve the event loop if
+ * throughput is set high.
+ */
+export class ThroughputDispatcher {
+    throughput;
+    id;
+    queue = [];
+    scheduled = false;
+    constructor(throughput = 16, id = 'throughput-dispatcher') {
+        this.throughput = throughput;
+        this.id = id;
+    }
+    execute(fn) {
+        this.queue.push(fn);
+        if (!this.scheduled) {
+            this.scheduled = true;
+            if (typeof setImmediate === 'function') {
+                setImmediate(() => this.drain());
+            }
+            else {
+                setTimeout(() => this.drain(), 0);
+            }
+        }
+    }
+    drain() {
+        this.scheduled = false;
+        let processed = 0;
+        while (processed < this.throughput && this.queue.length > 0) {
+            const fn = this.queue.shift();
+            runSafely(fn);
+            processed++;
+        }
+        if (this.queue.length > 0) {
+            this.scheduled = true;
+            if (typeof setImmediate === 'function') {
+                setImmediate(() => this.drain());
+            }
+            else {
+                setTimeout(() => this.drain(), 0);
+            }
+        }
+    }
+}
+export const Dispatchers = {
+    Immediate: () => new ImmediateDispatcher(),
+    Microtask: () => new MicrotaskDispatcher(),
+    Throughput: (throughput = 16) => new ThroughputDispatcher(throughput),
+};
+//# sourceMappingURL=Dispatcher.js.map

package/dist/Dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.js","sourceRoot":"","sources":["../src/Dispatcher.ts"],"names":[],"mappings":"AAWA,SAAS,SAAS,CAAC,EAA8B;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,EAAE,EAAE,CAAC;QACpB,IAAI,MAAM,IAAI,OAAQ,MAAwB,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YACnE,MAAwB,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACtC,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;YAC/D,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,GAAG,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACrB,EAAE,GAAG,sBAAsB,CAAC;IACrC,OAAO,CAAC,EAA8B;QACpC,cAAc,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACrB,EAAE,GAAG,sBAAsB,CAAC;IACrC,OAAO,CAAC,EAA8B;QACpC,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;YACvC,YAAY,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IAKH;IAJnB,EAAE,CAAS;IACZ,KAAK,GAAsC,EAAE,CAAC;IAC9C,SAAS,GAAG,KAAK,CAAC;IAE1B,YAA4B,aAAqB,EAAE,EAAE,KAAa,uBAAuB;QAA7D,eAAU,GAAV,UAAU,CAAa;QACjD,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,OAAO,CAAC,EAA8B;QACpC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;gBACvC,YAAY,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK;QACX,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,OAAO,SAAS,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YAC/B,SAAS,CAAC,EAAE,CAAC,CAAC;YACd,SAAS,EAAE,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;YACtB,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;gBACvC,YAAY,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE;IAC1C,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE;IAC1C,UAAU,EAAE,CAAC,aAAqB,EAAE,EAAE,EAAE,CAAC,IAAI,oBAAoB,CAAC,UAAU,CAAC;CAC9E,CAAC"}

package/dist/EventStream.d.ts

@@ -0,0 +1,58 @@
+import type { ActorRef } from './ActorRef.js';
+/**
+ * A simple system-wide pub/sub bus.  Subscribers register against a
+ * channel (a class constructor); publications are matched using
+ * `instanceof`, so subclasses are delivered to base-class subscribers.
+ *
+ * **Predicate-filtered subscriptions (#85).**  Each subscription
+ * may carry an optional predicate that runs against the event before
+ * delivery — only events the predicate accepts are `tell`'d to the
+ * subscriber.  Useful for high-frequency channels (cluster events,
+ * metrics) where the consumer only cares about a slice of the
+ * traffic and would otherwise have to filter inside its own
+ * `onReceive`.  A predicate that throws is treated as "no match"
+ * for that delivery; the subscription stays active.
+ */
+type Class<T> = new (...args: any[]) => T;
+/**
+ * Optional minimal-logger hook for the bus.  ActorSystem assigns its
+ * own logger here after construction; if unset (e.g. ad-hoc test
+ * use), predicate failures are silently swallowed.
+ */
+export interface EventStreamLogger {
+    warn(message: string, ...args: unknown[]): void;
+}
+export declare class EventStream {
+    private subs;
+    /**
+     * Optional logger used to surface predicate failures.  Assigned by
+     * `ActorSystem` once its main logger has been constructed; tests
+     * that instantiate `EventStream` directly can leave it `undefined`
+     * — the bus stays functional, errors just stay silent.
+     */
+    log?: EventStreamLogger;
+    /**
+     * Subscribe an actor ref to a channel (class).  Returns true if a
+     * new subscription was added; false if a duplicate was rejected.
+     *
+     * **Dedup rules.**  Without `predicate`, only one subscription per
+     * `(subscriber, channel)` is kept — re-calling `subscribe` is a
+     * no-op.  With a `predicate`, every call adds a new subscription:
+     * predicates are values without an identity contract, so dedup'ing
+     * across them would be unreliable; users wanting "replace this
+     * filter" should `unsubscribe` first.
+     */
+    subscribe<T>(subscriber: ActorRef, channel: Class<T>, predicate?: (event: T) => boolean): boolean;
+    /**
+     * Unsubscribe a `(subscriber, channel)` pair, or every subscription
+     * the actor holds when `channel` is omitted.  Removes ALL matching
+     * entries — including predicate-bearing ones; finer-grained removal
+     * (one specific predicate at a time) isn't supported because
+     * predicates have no stable identity.
+     */
+    unsubscribe<T>(subscriber: ActorRef, channel?: Class<T>): boolean;
+    /** Publish an event to all matching subscribers. */
+    publish(event: object): void;
+}
+export {};
+//# sourceMappingURL=EventStream.d.ts.map

package/dist/EventStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventStream.d.ts","sourceRoot":"","sources":["../src/EventStream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAS1C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjD;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,IAAI,CAAsB;IAElC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;IAExB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,CAAC,EACT,UAAU,EAAE,QAAQ,EACpB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAChC,OAAO;IAeV;;;;;;OAMG;IACH,WAAW,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO;IAYjE,oDAAoD;IACpD,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAqB7B"}

package/dist/EventStream.js

@@ -0,0 +1,74 @@
+export class EventStream {
+    subs = [];
+    /**
+     * Optional logger used to surface predicate failures.  Assigned by
+     * `ActorSystem` once its main logger has been constructed; tests
+     * that instantiate `EventStream` directly can leave it `undefined`
+     * — the bus stays functional, errors just stay silent.
+     */
+    log;
+    /**
+     * Subscribe an actor ref to a channel (class).  Returns true if a
+     * new subscription was added; false if a duplicate was rejected.
+     *
+     * **Dedup rules.**  Without `predicate`, only one subscription per
+     * `(subscriber, channel)` is kept — re-calling `subscribe` is a
+     * no-op.  With a `predicate`, every call adds a new subscription:
+     * predicates are values without an identity contract, so dedup'ing
+     * across them would be unreliable; users wanting "replace this
+     * filter" should `unsubscribe` first.
+     */
+    subscribe(subscriber, channel, predicate) {
+        if (!predicate) {
+            const already = this.subs.some((s) => s.subscriber.equals(subscriber) && s.channel === channel && !s.predicate);
+            if (already)
+                return false;
+        }
+        this.subs.push({
+            subscriber,
+            channel: channel,
+            predicate: predicate,
+        });
+        return true;
+    }
+    /**
+     * Unsubscribe a `(subscriber, channel)` pair, or every subscription
+     * the actor holds when `channel` is omitted.  Removes ALL matching
+     * entries — including predicate-bearing ones; finer-grained removal
+     * (one specific predicate at a time) isn't supported because
+     * predicates have no stable identity.
+     */
+    unsubscribe(subscriber, channel) {
+        const before = this.subs.length;
+        if (channel) {
+            this.subs = this.subs.filter((s) => !(s.subscriber.equals(subscriber) && s.channel === channel));
+        }
+        else {
+            this.subs = this.subs.filter((s) => !s.subscriber.equals(subscriber));
+        }
+        return this.subs.length !== before;
+    }
+    /** Publish an event to all matching subscribers. */
+    publish(event) {
+        for (const { subscriber, channel, predicate } of this.subs) {
+            if (!(event instanceof channel))
+                continue;
+            if (predicate) {
+                let accepted;
+                try {
+                    accepted = predicate(event);
+                }
+                catch (err) {
+                    // A throwing predicate must NOT break the bus for other
+                    // subscribers — treat as "no match" and keep going.
+                    this.log?.warn(`EventStream: predicate threw on ${channel.name} delivery — treating as no-match`, err);
+                    continue;
+                }
+                if (!accepted)
+                    continue;
+            }
+            subscriber.tell(event);
+        }
+    }
+}
+//# sourceMappingURL=EventStream.js.map

package/dist/EventStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventStream.js","sourceRoot":"","sources":["../src/EventStream.ts"],"names":[],"mappings":"AAkCA,MAAM,OAAO,WAAW;IACd,IAAI,GAAmB,EAAE,CAAC;IAElC;;;;;OAKG;IACH,GAAG,CAAqB;IAExB;;;;;;;;;;OAUG;IACH,SAAS,CACP,UAAoB,EACpB,OAAiB,EACjB,SAAiC;QAEjC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAC5B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,SAAS,CAChF,CAAC;YACF,IAAI,OAAO;gBAAE,OAAO,KAAK,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,UAAU;YACV,OAAO,EAAE,OAAyB;YAClC,SAAS,EAAE,SAAsD;SAClE,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,WAAW,CAAI,UAAoB,EAAE,OAAkB;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAC1B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CACnE,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC;IACrC,CAAC;IAED,oDAAoD;IACpD,OAAO,CAAC,KAAa;QACnB,KAAK,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,OAAO,CAAC;gBAAE,SAAS;YAC1C,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,QAAiB,CAAC;gBACtB,IAAI,CAAC;oBACH,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;gBAC9B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,wDAAwD;oBACxD,oDAAoD;oBACpD,IAAI,CAAC,GAAG,EAAE,IAAI,CACZ,mCAAmC,OAAO,CAAC,IAAI,kCAAkC,EACjF,GAAG,CACJ,CAAC;oBACF,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,QAAQ;oBAAE,SAAS;YAC1B,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,KAAc,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;CACF"}

package/dist/Extension.d.ts

@@ -0,0 +1,45 @@
+import type { ActorSystem } from './ActorSystem.js';
+/**
+ * Marker interface for everything that can be installed as an extension on
+ * an `ActorSystem`.  Its only real role is to let TypeScript distinguish
+ * extensions from arbitrary objects in the public API; implementations are
+ * free to expose any shape.
+ */
+export interface Extension {
+}
+/**
+ * Identifier + factory pair that the ActorSystem uses to lazily create and
+ * cache an extension singleton.  Conceptually: the `key` gives identity,
+ * the `createExtension` function produces the instance on first access.
+ */
+export interface ExtensionId<T extends Extension = Extension> {
+    readonly key: symbol;
+    readonly name: string;
+    createExtension(system: ActorSystem): T;
+}
+/**
+ * Helper: build an ExtensionId with a global-symbol-registered key so that
+ * two distinct imports of the same module resolve to the same extension.
+ */
+export declare function extensionId<T extends Extension>(name: string, factory: (system: ActorSystem) => T): ExtensionId<T>;
+/**
+ * Per-system registry.  Holds at most one instance per `ExtensionId.key`.
+ * First `.get(id)` triggers `id.createExtension(system)` and caches the
+ * result; subsequent calls return the same instance.
+ */
+export declare class Extensions {
+    private readonly system;
+    private readonly cache;
+    constructor(system: ActorSystem);
+    /** Return the extension for `id`, creating it lazily if needed. */
+    get<T extends Extension>(id: ExtensionId<T>): T;
+    /** True if the extension has already been created. */
+    has<T extends Extension>(id: ExtensionId<T>): boolean;
+    /** Register a pre-built instance — useful for tests that mock an extension. */
+    put<T extends Extension>(id: ExtensionId<T>, instance: T): void;
+    /** Eagerly initialise a batch of extensions (e.g. read from config). */
+    preload(ids: ExtensionId[]): void;
+    /** Snapshot the names of currently-loaded extensions — diagnostic only. */
+    loaded(): string[];
+}
+//# sourceMappingURL=Extension.d.ts.map

package/dist/Extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Extension.d.ts","sourceRoot":"","sources":["../src/Extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;CAAG;AAE7B;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAC7C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,GAClC,WAAW,CAAC,CAAC,CAAC,CAMhB;AAED;;;;GAIG;AACH,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAEzB,MAAM,EAAE,WAAW;IAEhD,mEAAmE;IACnE,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC;IAQ/C,sDAAsD;IACtD,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO;IAIrD,+EAA+E;IAC/E,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI;IAI/D,wEAAwE;IACxE,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,GAAG,IAAI;IAIjC,2EAA2E;IAC3E,MAAM,IAAI,MAAM,EAAE;CAInB"}

package/dist/Extension.js

@@ -0,0 +1,51 @@
+/**
+ * Helper: build an ExtensionId with a global-symbol-registered key so that
+ * two distinct imports of the same module resolve to the same extension.
+ */
+export function extensionId(name, factory) {
+    return {
+        key: Symbol.for(`actor-ts.ext.${name}`),
+        name,
+        createExtension: factory,
+    };
+}
+/**
+ * Per-system registry.  Holds at most one instance per `ExtensionId.key`.
+ * First `.get(id)` triggers `id.createExtension(system)` and caches the
+ * result; subsequent calls return the same instance.
+ */
+export class Extensions {
+    system;
+    cache = new Map();
+    constructor(system) {
+        this.system = system;
+    }
+    /** Return the extension for `id`, creating it lazily if needed. */
+    get(id) {
+        const cached = this.cache.get(id.key);
+        if (cached)
+            return cached;
+        const ext = id.createExtension(this.system);
+        this.cache.set(id.key, ext);
+        return ext;
+    }
+    /** True if the extension has already been created. */
+    has(id) {
+        return this.cache.has(id.key);
+    }
+    /** Register a pre-built instance — useful for tests that mock an extension. */
+    put(id, instance) {
+        this.cache.set(id.key, instance);
+    }
+    /** Eagerly initialise a batch of extensions (e.g. read from config). */
+    preload(ids) {
+        for (const id of ids)
+            this.get(id);
+    }
+    /** Snapshot the names of currently-loaded extensions — diagnostic only. */
+    loaded() {
+        return Array.from(this.cache.keys())
+            .map(k => Symbol.keyFor(k) ?? String(k));
+    }
+}
+//# sourceMappingURL=Extension.js.map

package/dist/Extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Extension.js","sourceRoot":"","sources":["../src/Extension.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,OAAmC;IAEnC,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC;QACvC,IAAI;QACJ,eAAe,EAAE,OAAO;KACzB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAGQ;IAFZ,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAEtD,YAA6B,MAAmB;QAAnB,WAAM,GAAN,MAAM,CAAa;IAAG,CAAC;IAEpD,mEAAmE;IACnE,GAAG,CAAsB,EAAkB;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAkB,CAAC;QACvD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,GAAG,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC5B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,sDAAsD;IACtD,GAAG,CAAsB,EAAkB;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,+EAA+E;IAC/E,GAAG,CAAsB,EAAkB,EAAE,QAAW;QACtD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;IAED,wEAAwE;IACxE,OAAO,CAAC,GAAkB;QACxB,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,2EAA2E;IAC3E,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;aACjC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC;CACF"}