@peerbit/shared-log 13.2.24 → 13.2.25

package/dist/src/instance-lifecycle.d.ts

@@ -0,0 +1,117 @@
+export type InstanceLifecyclePhase = "opening" | "active" | "poisoned" | "terminating" | "closed";
+export type InstanceLifecycleTerminalReason = "close" | "drop" | "internal-close";
+export type InstanceLifecycleDeps = {
+    /** host._instanceLifecycle — identity anchor for isCurrent() */
+    getCurrentLifecycle: () => InstanceLifecycle | undefined;
+    /** host._closeController */
+    getCloseController: () => AbortController | undefined;
+    /** host._replicationRangeMutationFailure (poison latch, fence A2) */
+    getPoisonFailure: () => unknown;
+    /** host.closed */
+    isHostClosed: () => boolean;
+    /** host.isTerminating() — closed || parent-detach || closeController aborted */
+    isHostTerminating: () => boolean;
+    /** host._checkedPrune — identity only, never dereferenced (fence A3) */
+    getCheckedPruneCoordinator: () => object | undefined;
+    /** host._replicationRangeMutationsClosing (terminal lane fence, A4) */
+    areRangeMutationsClosing: () => boolean;
+    /** host._pruneRemovesClosing (terminal lane fence, A4) */
+    arePruneRemovesClosing: () => boolean;
+    /** host.pruneDebouncedFn — identity only */
+    getPruneDebouncer: () => object | undefined;
+    /** host.replicationChangeDebounceFn — identity only */
+    getReplicationChangeDebouncer: () => object | undefined;
+    /** host.rebalanceParticipationDebounced — identity only */
+    getRebalanceDebouncer: () => object | undefined;
+};
+export declare class InstanceLifecycle {
+    private readonly deps;
+    roleGeneration: number;
+    _receiveOwnershipRevision: number;
+    _receiveOwnershipMutationAdmissions: number;
+    readonly ownershipLifecycleController: AbortController;
+    membershipLifecycleController?: AbortController;
+    declaredPhase: InstanceLifecyclePhase;
+    terminalReason?: InstanceLifecycleTerminalReason;
+    poisonCause?: unknown;
+    constructor(deps: InstanceLifecycleDeps);
+    markOpenComplete(): void;
+    beginTerminal(reason: InstanceLifecycleTerminalReason): void;
+    markPoisoned(cause: unknown): void;
+    /** ≡ legacy SharedLog.stopRepairLifecycle body (`controller?.abort()`),
+     * and the abort half of legacy startRepairLifecycle. Abort-in-place: the
+     * lifecycle identity is untouched (the poison contract — poison never
+     * rotates the lifecycle, so captures keep passing the identity term and
+     * fail on `signal.aborted`/poison exactly as before). */
+    abortOwnership(): void;
+    /** ≡ the legacy guarded abort in stopSubscriptionChangeCallbackAdmission:
+     * `if (!c?.signal.aborted) c?.abort(reason)`. */
+    abortMembership(reason?: unknown): void;
+    /** ≡ legacy `this._replicationLifecycleController = new AbortController()`
+     * in resetSubscriptionChangeCallbackTracking. Called exactly once per
+     * lifecycle, from open(); plain assignment kept (KEEP-OLD overwrite: the
+     * predecessor either is undefined or was aborted at close/drop). A
+     * direct out-of-open rotation (test-only) leaves the NEW lifecycle's
+     * membership undefined until the next open — a deliberate divergence
+     * from legacy, where the host field survived direct rotations; the two
+     * observables that path uses are pinned in the spec. */
+    beginMembership(): AbortController;
+    bumpRoleGeneration(): number;
+    isRoleCurrent(capturedRoleGeneration: number): boolean;
+    isCurrent(): boolean;
+    phase(): InstanceLifecyclePhase;
+    /** ≡ SharedLog.isRepairLifecycleActive(controller). Stage 4 note: the
+     * identity term compares against the OWNED controller. For a stale
+     * captured lifecycle with its co-captured controller the term now
+     * passes where the legacy host-current compare failed; the predicate
+     * still returns false via `signal.aborted`, guaranteed by the rotation
+     * invariant (non-current ⇒ abortOwnership already ran — see the field
+     * comment above). */
+    isActiveFor(controller: AbortController | undefined): boolean;
+    /**
+     * Controller-free form for stage-3 seams. Because this object OWNS its
+     * ownership controller (stage 4), lifecycle and controller rotate
+     * together by construction, so `capturedLifecycle.isActive()` ⇔
+     * `isRepairLifecycleActive(capturedController)` for captures taken
+     * together — the equivalence the unit spec asserts.
+     */
+    isActive(): boolean;
+    /** ≡ SharedLog.throwIfReplicationOwnershipPoisoned — message and `cause`
+     * must stay byte-identical for stage-3 drop-in. */
+    throwIfPoisoned(): void;
+    /** ≡ SharedLog.throwIfReplicationOwnershipLifecycleInactive. */
+    throwIfInactive(controller?: AbortController | undefined): void;
+    /** ≡ SharedLog.captureReplicationOwnershipLifecycle, but returns the
+     * lifecycle; stage-3 sites capture this instead of the raw controller
+     * (which stays reachable via ownershipSignal()). */
+    capture(): InstanceLifecycle;
+    /** AbortControllers stay the signal carriers. */
+    ownershipSignal(): AbortSignal | undefined;
+    /** ≡ SharedLog.isReplicationLifecycleActive(controller).
+     * NOTE the asymmetry vs isActiveFor: this side uses isTerminating()
+     * (closeController + parent-detach), not `closed` — preserve exactly. */
+    isMembershipActiveFor(controller: AbortController | undefined): boolean;
+    membershipSignal(): AbortSignal | undefined;
+    closeSignal(): AbortSignal | undefined;
+    /** ≡ prune()'s isCheckedPruneLifecycleCurrent triple for captures taken
+     * at the same admission point. Stage 3 extension: an omitted
+     * `closeController` SKIPS that term (the non-prune() checked-prune seats
+     * never compared it — adding the compare would strengthen their
+     * predicates), and `controller` lets a seat honor an explicitly threaded
+     * (possibly stale) ownership capture instead of the current one. */
+    isCheckedPruneCurrent(coordinator: object | undefined, closeController?: AbortController, controller?: AbortController | undefined): boolean;
+    /** Exact fold of prune()'s throwIfCheckedPruneLifecycleInactive and of
+     * revalidateCheckedPruneOwnership's controller branch (there with the
+     * closeController term omitted). Error order MUST stay: poison Error →
+     * ownership TerminalOperationNotStartedError ("Replication ownership
+     * lifecycle is no longer active") → checked-prune
+     * TerminalOperationNotStartedError ("Checked prune lifecycle is no
+     * longer active"). */
+    throwIfCheckedPruneInactive(coordinator: object | undefined, closeController?: AbortController, controller?: AbortController | undefined): void;
+    areRangeMutationsClosing(): boolean;
+    arePruneRemovesClosing(): boolean;
+    isPruneDebouncerCurrent(fn: object | undefined): boolean;
+    isReplicationChangeDebouncerCurrent(fn: object | undefined): boolean;
+    isRebalanceDebouncerCurrent(fn: object | undefined): boolean;
+}
+//# sourceMappingURL=instance-lifecycle.d.ts.map

package/dist/src/instance-lifecycle.d.ts.map

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

package/dist/src/instance-lifecycle.js

@@ -0,0 +1,254 @@
+// One InstanceLifecycle per SharedLog.open(). Stage 2 of the
+// session/lifecycle refactor introduced the object as a WRAPPER over the
+// existing fences via late-bound readers; stage 3 migrated the documented
+// multi-fence seams onto this API; stage 4 makes it the physical owner of
+// the per-open state: the role sub-generation, the receive-ownership
+// counters, and the ownership/membership AbortControllers themselves (the
+// index.ts ratchet entries moved file-to-file into this file's baseline in
+// scripts/ci/check-fence-ratchet.mjs). The remaining deps are late-bound
+// readers for host state that outlives any single lifecycle (poison latch,
+// close controller, coordinator/debouncer identities).
+import { TerminalOperationNotStartedError } from "@peerbit/program";
+export class InstanceLifecycle {
+    deps;
+    // The ONLY state that physically moved in stage 2 (absorbed the former
+    // SharedLog._localReplicationRoleGeneration; the accessor shim was deleted
+    // in stage 3). Bumped by replicate()'s
+    // fixed-role replacement and by full unreplication WITHOUT rotating the
+    // lifecycle: unreplicate() deliberately keeps the store open, so admitted
+    // adaptive planners are invalidated by this sub-generation, not by
+    // retiring the instance identity.
+    roleGeneration = 0;
+    // Moved from SharedLog (fences C1/C2, same names — the sanctioned
+    // file-to-file ratchet move). Physically owned per-open counters read and
+    // written directly through the lifecycle owner; the fresh lifecycle object
+    // at open() IS the legacy reset-to-0 (same pattern as roleGeneration above).
+    //
+    // Receive-side ownership plans may span lower-log joins that invoke user
+    // code. Incremented synchronously with leader-cache invalidation so the
+    // handler can detect whether its pre-join plan needs one fresh
+    // post-persist audit.
+    _receiveOwnershipRevision = 0;
+    // Count of ownership-changing range mutations from queue admission
+    // through settlement, including mutations already pending when a receive
+    // starts.
+    _receiveOwnershipMutationAdmissions = 0;
+    // ---- stage 4: physically owned controllers (moved from SharedLog) ----
+    // Fences A1/A5; the index.ts ratchet entries _repairLifecycleController /
+    // _replicationLifecycleController moved file-to-file under these names.
+    // Rotate-with-the-lifecycle by construction: a fresh InstanceLifecycle IS
+    // the rotation of both controllers; within one lifecycle the ownership
+    // controller identity never changes (readonly) — poison and terminal
+    // paths abort it IN PLACE, exactly like the legacy un-reassigned host
+    // field. Background repair work can outlive the await that admitted it;
+    // the per-open replacement of this whole object keeps an older runner
+    // from dispatching into or mutating a freshly opened lifecycle.
+    //
+    // INVARIANT every rotation site must keep: whatever installs a new
+    // host._instanceLifecycle aborts the outgoing lifecycle's ownership
+    // controller in the same synchronous block (startRepairLifecycle does).
+    // The stale-capture predicates in isActiveFor lean on
+    // non-current ⇒ aborted now that the identity term compares against the
+    // owned field rather than the host-current controller.
+    ownershipLifecycleController = new AbortController();
+    // undefined until open() reaches resetSubscriptionChangeCallbackTracking
+    // (beginMembership) — preserves the legacy `?: AbortController` decl-site
+    // semantics for constructed-but-never-opened hosts.
+    membershipLifecycleController;
+    // Stage-2 bookkeeping. WRITE-ONLY in production paths: no query method
+    // consults these (phase() is derived from the wrapped fences), so a
+    // missed or doubled transition cannot change behavior. Stage 3 flips
+    // phase() onto declaredPhase once the transitions have soaked in CI.
+    declaredPhase = "opening";
+    terminalReason;
+    poisonCause;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ---- rotation-point transitions (stage 2: diagnostics only) ----
+    markOpenComplete() {
+        if (this.declaredPhase === "opening")
+            this.declaredPhase = "active";
+    }
+    beginTerminal(reason) {
+        this.terminalReason ??= reason;
+        if (this.declaredPhase !== "poisoned")
+            this.declaredPhase = "terminating";
+    }
+    markPoisoned(cause) {
+        this.poisonCause ??= cause;
+        this.declaredPhase = "poisoned";
+    }
+    // ---- owned-controller transitions (stage 4) ----
+    /** ≡ legacy SharedLog.stopRepairLifecycle body (`controller?.abort()`),
+     * and the abort half of legacy startRepairLifecycle. Abort-in-place: the
+     * lifecycle identity is untouched (the poison contract — poison never
+     * rotates the lifecycle, so captures keep passing the identity term and
+     * fail on `signal.aborted`/poison exactly as before). */
+    abortOwnership() {
+        this.ownershipLifecycleController.abort();
+    }
+    /** ≡ the legacy guarded abort in stopSubscriptionChangeCallbackAdmission:
+     * `if (!c?.signal.aborted) c?.abort(reason)`. */
+    abortMembership(reason) {
+        if (!this.membershipLifecycleController?.signal.aborted) {
+            this.membershipLifecycleController?.abort(reason);
+        }
+    }
+    /** ≡ legacy `this._replicationLifecycleController = new AbortController()`
+     * in resetSubscriptionChangeCallbackTracking. Called exactly once per
+     * lifecycle, from open(); plain assignment kept (KEEP-OLD overwrite: the
+     * predecessor either is undefined or was aborted at close/drop). A
+     * direct out-of-open rotation (test-only) leaves the NEW lifecycle's
+     * membership undefined until the next open — a deliberate divergence
+     * from legacy, where the host field survived direct rotations; the two
+     * observables that path uses are pinned in the spec. */
+    beginMembership() {
+        return (this.membershipLifecycleController = new AbortController());
+    }
+    // ---- role sub-generation (absorbed fence A6) ----
+    bumpRoleGeneration() {
+        return ++this.roleGeneration;
+    }
+    isRoleCurrent(capturedRoleGeneration) {
+        return this.roleGeneration === capturedRoleGeneration;
+    }
+    // ---- identity ----
+    isCurrent() {
+        return this.deps.getCurrentLifecycle() === this;
+    }
+    // ---- derived phase (single source of truth = the wrapped fences) ----
+    phase() {
+        if (this.deps.getPoisonFailure() !== undefined)
+            return "poisoned";
+        if (this.deps.isHostClosed())
+            return "closed";
+        // The legacy `ownership == null` arm is gone: a lifecycle object owns
+        // its controller, so the absent-controller state is unrepresentable
+        // (clones have no lifecycle and cannot reach phase()).
+        if (!this.isCurrent() || this.ownershipLifecycleController.signal.aborted) {
+            return "terminating";
+        }
+        return this.declaredPhase === "opening" ? "opening" : "active";
+    }
+    // ---- ownership half: exact folds of the legacy predicates ----
+    /** ≡ SharedLog.isRepairLifecycleActive(controller). Stage 4 note: the
+     * identity term compares against the OWNED controller. For a stale
+     * captured lifecycle with its co-captured controller the term now
+     * passes where the legacy host-current compare failed; the predicate
+     * still returns false via `signal.aborted`, guaranteed by the rotation
+     * invariant (non-current ⇒ abortOwnership already ran — see the field
+     * comment above). */
+    isActiveFor(controller) {
+        return (controller != null &&
+            controller === this.ownershipLifecycleController &&
+            !controller.signal.aborted &&
+            this.deps.getPoisonFailure() === undefined &&
+            !this.deps.isHostClosed());
+    }
+    /**
+     * Controller-free form for stage-3 seams. Because this object OWNS its
+     * ownership controller (stage 4), lifecycle and controller rotate
+     * together by construction, so `capturedLifecycle.isActive()` ⇔
+     * `isRepairLifecycleActive(capturedController)` for captures taken
+     * together — the equivalence the unit spec asserts.
+     */
+    isActive() {
+        return (this.isCurrent() && this.isActiveFor(this.ownershipLifecycleController));
+    }
+    /** ≡ SharedLog.throwIfReplicationOwnershipPoisoned — message and `cause`
+     * must stay byte-identical for stage-3 drop-in. */
+    throwIfPoisoned() {
+        const failure = this.deps.getPoisonFailure();
+        if (failure !== undefined) {
+            throw new Error("Replication ownership recovery is required before further planning", { cause: failure });
+        }
+    }
+    /** ≡ SharedLog.throwIfReplicationOwnershipLifecycleInactive. */
+    throwIfInactive(controller = this.ownershipLifecycleController) {
+        this.throwIfPoisoned();
+        if (!(this.isCurrent() && this.isActiveFor(controller))) {
+            throw new TerminalOperationNotStartedError("Replication ownership lifecycle is no longer active");
+        }
+    }
+    /** ≡ SharedLog.captureReplicationOwnershipLifecycle, but returns the
+     * lifecycle; stage-3 sites capture this instead of the raw controller
+     * (which stays reachable via ownershipSignal()). */
+    capture() {
+        this.throwIfInactive();
+        return this;
+    }
+    /** AbortControllers stay the signal carriers. */
+    ownershipSignal() {
+        return this.ownershipLifecycleController.signal;
+    }
+    // ---- membership half (fence A5): exact fold ----
+    /** ≡ SharedLog.isReplicationLifecycleActive(controller).
+     * NOTE the asymmetry vs isActiveFor: this side uses isTerminating()
+     * (closeController + parent-detach), not `closed` — preserve exactly. */
+    isMembershipActiveFor(controller) {
+        return (controller != null &&
+            controller === this.membershipLifecycleController &&
+            !controller.signal.aborted &&
+            !this.deps.isHostTerminating());
+    }
+    membershipSignal() {
+        return this.membershipLifecycleController?.signal;
+    }
+    closeSignal() {
+        return this.deps.getCloseController()?.signal;
+    }
+    // ---- checked-prune identity (seams 4 and 7) ----
+    /** ≡ prune()'s isCheckedPruneLifecycleCurrent triple for captures taken
+     * at the same admission point. Stage 3 extension: an omitted
+     * `closeController` SKIPS that term (the non-prune() checked-prune seats
+     * never compared it — adding the compare would strengthen their
+     * predicates), and `controller` lets a seat honor an explicitly threaded
+     * (possibly stale) ownership capture instead of the current one. */
+    isCheckedPruneCurrent(coordinator, closeController, controller = this.ownershipLifecycleController) {
+        return (this.isCurrent() &&
+            this.isActiveFor(controller) &&
+            coordinator === this.deps.getCheckedPruneCoordinator() &&
+            (closeController === undefined ||
+                closeController === this.deps.getCloseController()));
+    }
+    /** Exact fold of prune()'s throwIfCheckedPruneLifecycleInactive and of
+     * revalidateCheckedPruneOwnership's controller branch (there with the
+     * closeController term omitted). Error order MUST stay: poison Error →
+     * ownership TerminalOperationNotStartedError ("Replication ownership
+     * lifecycle is no longer active") → checked-prune
+     * TerminalOperationNotStartedError ("Checked prune lifecycle is no
+     * longer active"). */
+    throwIfCheckedPruneInactive(coordinator, closeController, controller = this.ownershipLifecycleController) {
+        this.throwIfInactive(controller);
+        if (coordinator !== this.deps.getCheckedPruneCoordinator() ||
+            (closeController !== undefined &&
+                closeController !== this.deps.getCloseController())) {
+            throw new TerminalOperationNotStartedError("Checked prune lifecycle is no longer active");
+        }
+    }
+    // ---- terminal lane fences (A4): exposed, NOT folded into isActive ----
+    // Folding them would change which TerminalOperationNotStartedError message
+    // the admission sites throw ("Replication range mutations are closing",
+    // "Prune removals are closing") — a behavior change.
+    areRangeMutationsClosing() {
+        return this.deps.areRangeMutationsClosing();
+    }
+    arePruneRemovesClosing() {
+        return this.deps.arePruneRemovesClosing();
+    }
+    // ---- debouncer identities (seam 6 et al.) ----
+    // Bare === on purpose: at rebalanceParticipation the captured default
+    // parameter may be undefined and `undefined === undefined` legitimately
+    // passes today. A null-guard would break that.
+    isPruneDebouncerCurrent(fn) {
+        return fn === this.deps.getPruneDebouncer();
+    }
+    isReplicationChangeDebouncerCurrent(fn) {
+        return fn === this.deps.getReplicationChangeDebouncer();
+    }
+    isRebalanceDebouncerCurrent(fn) {
+        return fn === this.deps.getRebalanceDebouncer();
+    }
+}
+//# sourceMappingURL=instance-lifecycle.js.map

package/dist/src/instance-lifecycle.js.map

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

package/dist/src/join-warmup.d.ts

@@ -0,0 +1,86 @@
+/**
+ * One WarmupSession per join-warmup attempt window for a target. The
+ * instance IS the legacy opaque generation token — always compared by
+ * identity, never inspected — now carrying diagnostics. Rotation points are
+ * unchanged: created on demand, dropped at cancelJoinWarmupTarget so the
+ * next touch mints a fresh identity. Deliberately NOT hosted on
+ * PeerSession: warmup windows rotate independently of subscription epochs
+ * (poison and committed removals leave the subscription session alone), and
+ * a warmup target may have no session at all — auto-creating one as a
+ * warmup side effect would flip `isCurrent(peer, null)` from true to false
+ * at every receive-admission seat.
+ */
+export declare class WarmupSession {
+    readonly target: string;
+    readonly createdAt: number;
+    constructor(target: string);
+}
+export type JoinWarmupSendState<E> = {
+    bypassKnownPeerHints: boolean;
+    entries: Map<string, E>;
+    session: WarmupSession;
+    lastCompletedAt: number;
+    pending: boolean;
+    running: boolean;
+};
+export type JoinWarmupRetryTimer = {
+    handle: ReturnType<typeof setTimeout>;
+    resolve?: () => void;
+};
+export type JoinWarmupScheduledRetryBatch<E> = {
+    bypassKnownPeerHints: boolean;
+    entries: Map<string, E>;
+    remainingAttempts: number;
+};
+export type JoinWarmupScheduledRetryCohort<E> = {
+    batches: JoinWarmupScheduledRetryBatch<E>[];
+    dueAt: number;
+};
+export type JoinWarmupScheduledRetrySlot<E> = {
+    cohorts: JoinWarmupScheduledRetryCohort<E>[];
+    head: number;
+    timer?: JoinWarmupRetryTimer;
+    timerDueAt?: number;
+};
+export type JoinWarmupScheduledRetries<E> = {
+    session: WarmupSession;
+    slotsByDelay: Map<number, JoinWarmupScheduledRetrySlot<E>>;
+};
+export type JoinWarmupDeps<E> = {
+    isLifecycleActive: (controller: AbortController) => boolean;
+    getCurrentLifecycleController: () => AbortController;
+    getRepairRetryTimers: () => Set<ReturnType<typeof setTimeout>>;
+    isClosed: () => boolean;
+    onTargetCancelled: (target: string) => void;
+    bumpSimpleFallbackPasses: () => void;
+    sendEntriesSimple: (target: string, entries: ReadonlyMap<string, E>, options: {
+        bypassKnownPeers: boolean;
+        bypassRecentKnownPeers: boolean;
+        isStillCurrent: () => boolean;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    logError: (error: any) => void;
+};
+export declare class JoinWarmupCoordinator<E> {
+    private readonly deps;
+    _warmupSessionsByTarget: Map<string, WarmupSession>;
+    _joinWarmupSendStateByTarget: Map<string, JoinWarmupSendState<E>>;
+    _joinWarmupRetryTimersByTarget: Map<string, Set<JoinWarmupRetryTimer>>;
+    _joinWarmupScheduledRetriesByTarget: Map<string, JoinWarmupScheduledRetries<E>>;
+    _repairSweepWarmupSessionByTarget: Map<string, WarmupSession>;
+    constructor(deps: JoinWarmupDeps<E>);
+    reset(): void;
+    ensureWarmupSession(target: string): WarmupSession;
+    clearRepairSweepWarmupSessions(): void;
+    trackJoinWarmupTimer(target: string, timer: JoinWarmupRetryTimer): void;
+    untrackJoinWarmupTimer(target: string, timer: JoinWarmupRetryTimer): void;
+    cancelJoinWarmupTimers(target: string): void;
+    cancelJoinWarmupTarget(target: string): void;
+    cancelAllJoinWarmupTargets(): void;
+    sleepJoinWarmupTracked(target: string, delayMs: number, repairLifecycleController: AbortController): Promise<void>;
+    scheduleJoinWarmupRetries(target: string, session: WarmupSession, delaysMs: Iterable<number>, entries: ReadonlyMap<string, E>, bypassKnownPeerHints: boolean, repairLifecycleController?: AbortController): void;
+    armJoinWarmupRetrySlot(target: string, scheduled: JoinWarmupScheduledRetries<E>, delayMs: number, slot: JoinWarmupScheduledRetrySlot<E>, repairLifecycleController: AbortController): void;
+    queueJoinWarmupSend(target: string, session: WarmupSession, entries: ReadonlyMap<string, E>, bypassKnownPeerHints: boolean, repairLifecycleController?: AbortController): void;
+    drainJoinWarmupSends(target: string, state: JoinWarmupSendState<E>, repairLifecycleController: AbortController): Promise<void>;
+}
+//# sourceMappingURL=join-warmup.d.ts.map

package/dist/src/join-warmup.d.ts.map

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