actor-ts 0.9.0

package/dist/serialization/SerializationExtension.js

@@ -0,0 +1,105 @@
+import { extensionId } from '../Extension.js';
+import { CborSerializer } from './CborSerializer.js';
+import { JsonSerializer } from './JsonSerializer.js';
+import { SerializationError } from './Serializer.js';
+/**
+ * Registry that resolves serializers by ID (at decode time) and by message
+ * class (at encode time).  JSON (id=1) is the built-in fallback; CBOR
+ * (id=2) is registered and available but used only when explicitly bound
+ * to a class or asked for by ID.
+ *
+ * Will graduate to an `ExtensionId<SerializationExtension>` once the
+ * Extensions mechanism (P1.2) lands — until then it is constructed
+ * directly inside `ActorSystem`.
+ */
+export class SerializationExtension {
+    byId = new Map();
+    byClass = new Map();
+    _default;
+    constructor() {
+        this._default = new JsonSerializer();
+        this.register(this._default);
+        this.register(new CborSerializer());
+    }
+    /** The serializer used for values with no explicit class binding.  Defaults to JSON. */
+    get defaultSerializer() { return this._default; }
+    setDefault(serializer) {
+        if (!this.byId.has(serializer.id))
+            this.register(serializer);
+        this._default = serializer;
+    }
+    register(serializer) {
+        const existing = this.byId.get(serializer.id);
+        if (existing && existing !== serializer) {
+            throw new SerializationError(`Serializer id ${serializer.id} already registered as "${existing.name}"`);
+        }
+        this.byId.set(serializer.id, serializer);
+    }
+    /** Bind a message class to a specific serializer (by ID). */
+    bind(cls, serializerId) {
+        const ser = this.byId.get(serializerId);
+        if (!ser)
+            throw new SerializationError(`No serializer registered with id ${serializerId}`);
+        this.byClass.set(cls, ser);
+    }
+    /** Find a serializer by ID (used by decoders). */
+    findById(id) {
+        return this.byId.get(id);
+    }
+    /** Look up by ID or throw. */
+    requireById(id) {
+        const s = this.findById(id);
+        if (!s)
+            throw new SerializationError(`No serializer registered with id ${id}`);
+        return s;
+    }
+    /**
+     * Find the appropriate serializer for a value.  Lookup order:
+     *   1. Exact constructor binding (`bind(Foo, 2)`).
+     *   2. Walk the prototype chain for a bound ancestor.
+     *   3. Default (JSON).
+     */
+    findFor(value) {
+        if (value === null || value === undefined)
+            return this._default;
+        const proto = Object.getPrototypeOf(value);
+        const ctor = proto?.constructor;
+        if (ctor) {
+            const direct = this.byClass.get(ctor);
+            if (direct)
+                return direct;
+            // Walk prototype chain.
+            let walker = ctor;
+            while (walker) {
+                const found = this.byClass.get(walker);
+                if (found)
+                    return found;
+                const parent = Object.getPrototypeOf(walker);
+                walker = parent && parent !== Function.prototype ? parent : undefined;
+            }
+        }
+        return this._default;
+    }
+    /* ------------------------- Convenience encode/decode ------------------------ */
+    /** Encode a value using the resolved serializer; returns a tagged SerializedValue. */
+    encode(value) {
+        const ser = this.findFor(value);
+        return {
+            serializerId: ser.id,
+            manifest: ser.manifest(value),
+            bytes: ser.toBinary(value),
+        };
+    }
+    /** Decode a SerializedValue using the serializer it names. */
+    decode(sv) {
+        const ser = this.requireById(sv.serializerId);
+        return ser.fromBinary(sv.bytes, sv.manifest);
+    }
+    /** Snapshot registered serializer IDs — useful for diagnostics. */
+    registeredIds() {
+        return Array.from(this.byId.keys()).sort((a, b) => a - b);
+    }
+}
+/** ExtensionId for the stock serialisation registry — install via `system.extension(...)`. */
+export const SerializationExtensionId = extensionId('SerializationExtension', (_system) => new SerializationExtension());
+//# sourceMappingURL=SerializationExtension.js.map

package/dist/serialization/SerializationExtension.js.map

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

package/dist/serialization/Serializer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Serializers encode values into bytes for transport between nodes and for
+ * persistence.  The contract is intentionally small so that custom formats
+ * (Protobuf, Avro, msgpack, …) slot in as plug-ins without touching core.
+ */
+export interface Serializer<T = unknown> {
+    /**
+     * Stable identifier that is embedded in every frame.  Numbers 1..99 are
+     * reserved for the actor-ts built-ins (JSON=1, CBOR=2).  User-defined
+     * serializers SHOULD use IDs ≥ 100.
+     */
+    readonly id: number;
+    /** Human-readable name, surfaced in diagnostics. */
+    readonly name: string;
+    /** True when this serializer is willing to encode the given value. */
+    includesManifest: boolean;
+    /**
+     * Return a tag describing the concrete type of `obj` so the decoder knows
+     * how to reconstruct it.  Typical values: class name, event ID, "map",
+     * "null", etc.  May return an empty string for serializers that don't
+     * need a manifest.
+     */
+    manifest(obj: T): string;
+    /** Encode to binary. */
+    toBinary(obj: T): Uint8Array;
+    /**
+     * Decode from binary.  `manifest` is whatever was produced on the other
+     * side (or '' when the serializer does not use one).
+     */
+    fromBinary(bytes: Uint8Array, manifest: string): T;
+}
+/**
+ * Marker payload emitted whenever a serializer round-trips a value through
+ * the wire — exposed for debugging tools and wire-level tests.
+ */
+export interface SerializedValue {
+    readonly serializerId: number;
+    readonly manifest: string;
+    readonly bytes: Uint8Array;
+}
+export declare class SerializationError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=Serializer.d.ts.map

package/dist/serialization/Serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.d.ts","sourceRoot":"","sources":["../../src/serialization/Serializer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC;IAEzB,wBAAwB;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC;IAE7B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/serialization/Serializer.js

@@ -0,0 +1,7 @@
+export class SerializationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SerializationError';
+    }
+}
+//# sourceMappingURL=Serializer.js.map

package/dist/serialization/Serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Serializer.js","sourceRoot":"","sources":["../../src/serialization/Serializer.ts"],"names":[],"mappings":"AA+CA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/serialization/index.d.ts

@@ -0,0 +1,7 @@
+export type { Serializer, SerializedValue } from './Serializer.js';
+export { SerializationError } from './Serializer.js';
+export { JsonSerializer } from './JsonSerializer.js';
+export { CborSerializer } from './CborSerializer.js';
+export { CborDecoder, CborEncoder, CborDecodeError, CborEncodeError } from './CborCodec.js';
+export { SerializationExtension, SerializationExtensionId } from './SerializationExtension.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/serialization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/serialization/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/serialization/index.js

@@ -0,0 +1,6 @@
+export { SerializationError } from './Serializer.js';
+export { JsonSerializer } from './JsonSerializer.js';
+export { CborSerializer } from './CborSerializer.js';
+export { CborDecoder, CborEncoder, CborDecodeError, CborEncodeError } from './CborCodec.js';
+export { SerializationExtension, SerializationExtensionId } from './SerializationExtension.js';
+//# sourceMappingURL=index.js.map

package/dist/serialization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/serialization/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/testkit/ManualScheduler.d.ts

@@ -0,0 +1,35 @@
+import type { ActorRef } from '../ActorRef.js';
+import { Scheduler, type Cancellable } from '../Scheduler.js';
+/**
+ * Scheduler implementation driven entirely by `advance(ms)` — the wall
+ * clock is ignored.  Swap this into `ActorSystem.create(name, { scheduler })`
+ * in tests to get deterministic timer behaviour.
+ */
+export declare class ManualScheduler extends Scheduler {
+    private _now;
+    private tasks;
+    private idCounter;
+    private stopped;
+    scheduleOnceFn(delayMs: number, fn: () => void): Cancellable;
+    scheduleOnce<T>(delayMs: number, target: ActorRef<T>, message: T, sender?: ActorRef | null): Cancellable;
+    scheduleAtFixedRateFn(initialDelayMs: number, intervalMs: number, fn: () => void): Cancellable;
+    scheduleAtFixedRate<T>(initialDelayMs: number, intervalMs: number, target: ActorRef<T>, message: T, sender?: ActorRef | null): Cancellable;
+    shutdown(): void;
+    /** Current virtual time in ms (monotonic, advances only via `advance`). */
+    now(): number;
+    /** Number of scheduled non-cancelled tasks. */
+    get pendingCount(): number;
+    /**
+     * Advance virtual time by `ms`.  Any timers whose `fireAt` falls inside
+     * the advanced range fire in deterministic order (earliest first, ties
+     * broken by insertion order).
+     */
+    advance(ms: number): void;
+    /** Jump directly to the time of the next pending task (or no-op if none). */
+    advanceToNext(): void;
+    private add;
+    private peekNext;
+    private peekAny;
+    private pruneCancelled;
+}
+//# sourceMappingURL=ManualScheduler.d.ts.map

package/dist/testkit/ManualScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ManualScheduler.d.ts","sourceRoot":"","sources":["../../src/testkit/ManualScheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAW9D;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,OAAO,CAAS;IAIf,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,WAAW;IAI5D,YAAY,CAAC,CAAC,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,CAAC,EACV,MAAM,GAAE,QAAQ,GAAG,IAAW,GAC7B,WAAW;IAOL,qBAAqB,CAC5B,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,IAAI,GACb,WAAW;IAQL,mBAAmB,CAAC,CAAC,EAC5B,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,CAAC,EACV,MAAM,GAAE,QAAQ,GAAG,IAAW,GAC7B,WAAW;IAQL,QAAQ,IAAI,IAAI;IAOzB,2EAA2E;IAC3E,GAAG,IAAI,MAAM;IAEb,+CAA+C;IAC/C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAsBzB,6EAA6E;IAC7E,aAAa,IAAI,IAAI;IAOrB,OAAO,CAAC,GAAG;IAgBX,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,cAAc;CAGvB"}

package/dist/testkit/ManualScheduler.js

@@ -0,0 +1,126 @@
+import { Scheduler } from '../Scheduler.js';
+/**
+ * Scheduler implementation driven entirely by `advance(ms)` — the wall
+ * clock is ignored.  Swap this into `ActorSystem.create(name, { scheduler })`
+ * in tests to get deterministic timer behaviour.
+ */
+export class ManualScheduler extends Scheduler {
+    _now = 0;
+    tasks = [];
+    idCounter = 0;
+    stopped = false;
+    /* -------------------------- Scheduler API overrides -------------------------- */
+    scheduleOnceFn(delayMs, fn) {
+        return this.add({ fireAt: this._now + delayMs, fn });
+    }
+    scheduleOnce(delayMs, target, message, sender = null) {
+        return this.add({
+            fireAt: this._now + delayMs,
+            fn: () => target.tell(message, sender),
+        });
+    }
+    scheduleAtFixedRateFn(initialDelayMs, intervalMs, fn) {
+        return this.add({
+            fireAt: this._now + initialDelayMs,
+            fn,
+            repeat: { intervalMs },
+        });
+    }
+    scheduleAtFixedRate(initialDelayMs, intervalMs, target, message, sender = null) {
+        return this.add({
+            fireAt: this._now + initialDelayMs,
+            fn: () => target.tell(message, sender),
+            repeat: { intervalMs },
+        });
+    }
+    shutdown() {
+        this.stopped = true;
+        this.tasks = [];
+    }
+    /* --------------------------- Virtual-time controls --------------------------- */
+    /** Current virtual time in ms (monotonic, advances only via `advance`). */
+    now() { return this._now; }
+    /** Number of scheduled non-cancelled tasks. */
+    get pendingCount() {
+        return this.tasks.filter(t => !t.cancelled).length;
+    }
+    /**
+     * Advance virtual time by `ms`.  Any timers whose `fireAt` falls inside
+     * the advanced range fire in deterministic order (earliest first, ties
+     * broken by insertion order).
+     */
+    advance(ms) {
+        if (this.stopped)
+            return;
+        const target = this._now + ms;
+        while (true) {
+            const next = this.peekNext(target);
+            if (!next)
+                break;
+            this._now = next.fireAt;
+            try {
+                next.fn();
+            }
+            catch (e) {
+                // Mirror the real scheduler: log, do not propagate.
+                console.error('[ManualScheduler] task threw:', e);
+            }
+            if (next.repeat) {
+                next.fireAt = this._now + next.repeat.intervalMs;
+            }
+            else {
+                next.cancelled = true;
+            }
+            this.pruneCancelled();
+        }
+        this._now = target;
+        this.pruneCancelled();
+    }
+    /** Jump directly to the time of the next pending task (or no-op if none). */
+    advanceToNext() {
+        const next = this.peekAny();
+        if (next)
+            this.advance(Math.max(0, next.fireAt - this._now));
+    }
+    /* ---------------------------------- Internals --------------------------------- */
+    add(partial) {
+        if (this.stopped) {
+            return { cancel: () => false, isCancelled: true };
+        }
+        const task = { id: ++this.idCounter, cancelled: false, ...partial };
+        this.tasks.push(task);
+        return {
+            cancel: () => {
+                if (task.cancelled)
+                    return false;
+                task.cancelled = true;
+                return true;
+            },
+            get isCancelled() { return task.cancelled; },
+        };
+    }
+    peekNext(upTo) {
+        let best = null;
+        for (const t of this.tasks) {
+            if (t.cancelled || t.fireAt > upTo)
+                continue;
+            if (!best || t.fireAt < best.fireAt || (t.fireAt === best.fireAt && t.id < best.id))
+                best = t;
+        }
+        return best;
+    }
+    peekAny() {
+        let best = null;
+        for (const t of this.tasks) {
+            if (t.cancelled)
+                continue;
+            if (!best || t.fireAt < best.fireAt || (t.fireAt === best.fireAt && t.id < best.id))
+                best = t;
+        }
+        return best;
+    }
+    pruneCancelled() {
+        this.tasks = this.tasks.filter(t => !t.cancelled);
+    }
+}
+//# sourceMappingURL=ManualScheduler.js.map

package/dist/testkit/ManualScheduler.js.map

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

package/dist/testkit/MultiNodeSpec.d.ts

@@ -0,0 +1,132 @@
+import { ActorSystem } from '../ActorSystem.js';
+import { Cluster, type ClusterSettings } from '../cluster/Cluster.js';
+import type { DowningProvider } from '../cluster/downing/index.js';
+import { type Member } from '../cluster/Member.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { LogLevel } from '../Logger.js';
+/**
+ * Multi-node-spec test harness — runs multiple `ActorSystem` + `Cluster`
+ * instances in **one** process, routed through `MultiNodeTransport`,
+ * with helpers for the operations real multi-node tests actually need:
+ *
+ *   - **Spin up N roles** at once (`new MultiNodeSpec({ roles: ['a','b','c'] })`),
+ *     each with its own ActorSystem + Cluster + NodeAddress.  The first
+ *     role acts as the seed by default.
+ *   - **Cluster API access** per role — `clusterFor('a')`, `systemFor('b')`.
+ *   - **Crash simulation** — `crash(role)` shuts down a node's transport
+ *     ungracefully (other nodes detect via failure-detection); `leave(role)`
+ *     does a graceful exit.
+ *   - **Network partition** — `partition(roleA, roleB)` bidirectionally
+ *     blocks messages between the two roles; `heal(...)` undoes it.
+ *   - **Synchronization helpers** — `awaitMembers`, `awaitMemberStatus`,
+ *     `awaitLeader` — poll-based assertions with a default 10 s timeout
+ *     so race-prone multi-node tests have a deterministic exit point
+ *     (rather than hanging forever).
+ *
+ * In-process means single event-loop — that loses true parallelism, but
+ * gains determinism, fast test starts, and clean stack traces.  The
+ * worker-thread-based variant could be a follow-up if real concurrency
+ * matters.  For the scenarios we're targeting (sharding rebalance,
+ * pubsub cross-node, singleton failover), in-process is enough.
+ *
+ *   const spec = new MultiNodeSpec({ roles: ['a', 'b', 'c'] });
+ *   await spec.start();
+ *   await spec.awaitMembers('a', 3);
+ *
+ *   spec.systemFor('b').spawnAnonymous(...);
+ *   await spec.crash('b');
+ *   await spec.awaitMembers('a', 2);
+ *
+ *   await spec.stop();
+ */
+export interface MultiNodeSpecSettings {
+    /** Role names — also act as system names; must be unique within the spec. */
+    readonly roles: ReadonlyArray<string>;
+    /**
+     * Roles that act as bootstrap seeds.  Defaults to `[roles[0]]` — the
+     * first role is the lone seed.  All other roles try to join via the
+     * seed list.
+     */
+    readonly seedRoles?: ReadonlyArray<string>;
+    /**
+     * Per-role address overrides.  Useful if a test wants pinned
+     * host:port pairs (e.g. for log readability).  If omitted, addresses
+     * are auto-allocated as `127.0.0.1:<base + index>` with a fresh base
+     * per spec.
+     */
+    readonly addresses?: Readonly<Record<string, {
+        host: string;
+        port: number;
+    }>>;
+    /**
+     * Failure-detector overrides.  Multi-node tests typically want the
+     * detector tightened so dead nodes are noticed within seconds rather
+     * than the production default.  See `Cluster.ts` for the field set.
+     */
+    readonly failureDetector?: ClusterSettings['failureDetector'];
+    /** Gossip interval, default 100 ms (vs production 1 s). */
+    readonly gossipIntervalMs?: number;
+    /** How long synchronous `await*` helpers wait before throwing.  Default 10 s. */
+    readonly awaitTimeoutMs?: number;
+    /** Logger — defaults to NoopLogger so tests stay quiet. */
+    readonly logLevel?: LogLevel;
+    /**
+     * Per-role split-brain resolver factory.  Called once per role at
+     * `start()` time; the returned provider is wired into that role's
+     * cluster via `ClusterSettings.downing`.  Each role typically gets
+     * its OWN provider instance (some strategies are stateful — e.g.
+     * `LeaseMajority` holds a per-replica acquire result).  Pass
+     * `undefined` for a role that should run without downing.
+     */
+    readonly downing?: (role: string) => DowningProvider | undefined;
+}
+export declare class MultiNodeSpec {
+    private readonly settings;
+    private readonly nodes;
+    private started;
+    constructor(settings: MultiNodeSpecSettings);
+    /** Bring up every role. */
+    start(): Promise<void>;
+    /** Tear down every node.  Idempotent — safe to call after `crash()`. */
+    stop(): Promise<void>;
+    systemFor(role: string): ActorSystem;
+    clusterFor(role: string): Cluster;
+    addressFor(role: string): NodeAddress;
+    /** All roles currently registered, regardless of crashed/active state. */
+    allRoles(): string[];
+    /**
+     * Hard crash — shut down the transport so the node disappears
+     * abruptly.  Other nodes notice via failure detection (typically
+     * within `failureDetector.acceptableHeartbeatPause + threshold` ms).
+     * The terminated node's `cluster` and `system` references stay live
+     * for assertion purposes; calls to them post-crash will error.
+     */
+    crash(role: string): Promise<void>;
+    /** Graceful leave — node sends a Leaving gossip, then shuts down. */
+    leave(role: string): Promise<void>;
+    /** Bidirectional partition between two roles.  Both sides drop traffic to the other. */
+    partition(roleA: string, roleB: string): void;
+    /** Undo `partition(roleA, roleB)`. */
+    heal(roleA: string, roleB: string): void;
+    /**
+     * Wait until the named role's view of the cluster contains exactly
+     * `expectedCount` members in `up`-or-better state.  Throws on timeout.
+     */
+    awaitMembers(role: string, expectedCount: number, timeoutMs?: number): Promise<void>;
+    /**
+     * Wait until the named role's view shows `targetMember` (by role name)
+     * in the given status (`up`, `unreachable`, `down`, `removed`).
+     */
+    awaitMemberStatus(role: string, targetRole: string, status: Member['status'], timeoutMs?: number): Promise<void>;
+    /**
+     * Wait until the named role's view of the leader is `expectedLeaderRole`,
+     * or `null` to wait for "no leader".
+     */
+    awaitLeader(role: string, expectedLeaderRole: string | null, timeoutMs?: number): Promise<void>;
+    private requireNode;
+    private awaitCondition;
+    private snapshotMemberCount;
+    private snapshotMembers;
+    private snapshotLeader;
+}
+//# sourceMappingURL=MultiNodeSpec.d.ts.map

package/dist/testkit/MultiNodeSpec.d.ts.map

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