actor-ts 0.9.0

package/dist/persistence/PersistentActor.d.ts

@@ -0,0 +1,120 @@
+import { Actor } from '../Actor.js';
+import type { PersistentEvent, Snapshot } from './JournalTypes.js';
+import type { CompressionConfig, EncryptionConfig } from './PersistenceOptions.js';
+import type { EventAdapter, SnapshotAdapter } from './migration/Adapter.js';
+/**
+ * How often to take snapshots — called after every event apply.  Returning
+ * true means "snapshot the current state".
+ */
+export type SnapshotPolicy<State, Event> = (seq: number, state: State, event: Event) => boolean;
+/** Convenience: snapshot every N events. */
+export declare function everyNEvents<State, Event>(n: number): SnapshotPolicy<State, Event>;
+/**
+ * Classic-style event-sourced actor.  Subclasses override `onCommand`
+ * (which decides what to persist), `onEvent` (pure state update from the
+ * event), and optionally `onRecoveryComplete`.  Commands are automatically
+ * stashed while `persist(...)` is pending, so user code can assume the
+ * state is caught up by the time its callback fires.
+ *
+ *   class AccountActor extends PersistentActor<Cmd, Event, State> {
+ *     readonly persistenceId = 'account-42';
+ *     initialState(): State { return { balance: 0 }; }
+ *     onEvent(state: State, e: Event): State {
+ *       if (e.kind === 'deposited') return { balance: state.balance + e.amount };
+ *       return state;
+ *     }
+ *     onCommand(state: State, cmd: Cmd): void {
+ *       if (cmd.kind === 'deposit') {
+ *         this.persist({ kind: 'deposited', amount: cmd.amount }, (s) => {
+ *           this.sender?.tell({ ok: s.balance });
+ *         });
+ *       }
+ *     }
+ *   }
+ */
+export declare abstract class PersistentActor<Cmd, Event, State> extends Actor<Cmd> {
+    abstract readonly persistenceId: string;
+    /** Default initial state when no snapshot and no events exist. */
+    abstract initialState(): State;
+    /** Pure state-update function — MUST be deterministic. */
+    abstract onEvent(state: State, event: Event): State;
+    /** Handle an incoming command — typically calls `persist(event, cb)`. */
+    abstract onCommand(state: State, cmd: Cmd): void | Promise<void>;
+    /** Called once recovery finishes, with the final replayed state. */
+    onRecoveryComplete(_state: State): void | Promise<void>;
+    /** Called when recovery itself throws.  Default = propagate to supervision. */
+    onRecoveryFailure(reason: Error): void;
+    /** Snapshot policy — return true to snapshot the current state. */
+    snapshotPolicy(): SnapshotPolicy<State, Event>;
+    /** Optional tags attached to every persisted event (for Persistence Query). */
+    tagsFor(_event: Event): ReadonlyArray<string> | undefined;
+    /**
+     * Optional event adapter for schema evolution.  When defined, every
+     * persisted event is wrapped into a `{ _v, _t, _e }` envelope on the
+     * write path and unwrapped (with up-casting through the adapter) on
+     * the read path.  Recovery is **strict** when an adapter is set: a
+     * raw, non-envelope event in the journal will throw `MigrationError`.
+     * See `src/persistence/migration/`.
+     */
+    eventAdapter(): EventAdapter<Event> | undefined;
+    /**
+     * Optional snapshot adapter — same semantics as `eventAdapter`, but
+     * applied to the `state` blob persisted by the snapshot store.  When
+     * a snapshot adapter is set and a stored snapshot is not an envelope,
+     * recovery throws.
+     */
+    snapshotAdapter(): SnapshotAdapter<State> | undefined;
+    /**
+     * Per-actor compression — overrides the plugin default for THIS actor's
+     * snapshots.  Stores that don't compress (in-memory, SQLite, Cassandra)
+     * ignore the value.  Returning `undefined` (the default) defers to the
+     * plugin's resolver / configured default.
+     */
+    compression(): CompressionConfig | undefined;
+    /**
+     * Per-actor encryption — overrides the plugin default for THIS actor's
+     * snapshots.  Honoured by stores that encrypt at rest (object-storage);
+     * other stores ignore it.  Used on both the write path (encrypt) and
+     * the read path (derive subkey from master to decrypt).
+     */
+    encryption(): EncryptionConfig | undefined;
+    private _state;
+    private _seq;
+    private _journal;
+    private _snapshotStore;
+    private _recovering;
+    /** Set while a persist is in flight — incoming commands get stashed. */
+    private _persisting;
+    private _pendingCallbacks;
+    /** Current state — only reliable after recovery. */
+    protected get state(): State;
+    /** Highest sequence number reflected in `state`. */
+    protected get lastSequenceNr(): number;
+    /** True while the actor is still replaying history. */
+    protected get recovering(): boolean;
+    preStart(): Promise<void>;
+    private recover;
+    onReceive(message: Cmd): Promise<void>;
+    /**
+     * Persist a single event.  The callback runs once the event has been
+     * applied to the state — use it to reply to the sender.  Further
+     * incoming commands are deferred until the callback returns.
+     */
+    protected persist(event: Event, cb?: (state: State) => void | Promise<void>): Promise<void>;
+    /** Persist several events atomically.  Must also be awaited in onCommand. */
+    protected persistAll(events: ReadonlyArray<Event>, cb?: (state: State) => void | Promise<void>): Promise<void>;
+    /** Force a snapshot of the current state. */
+    protected saveSnapshot(): Promise<Snapshot<State>>;
+    private saveSnapshotNow;
+    /**
+     * Build the per-call `PersistenceOptions` from the actor's hooks.
+     * Returns `undefined` when neither hook is set so the store defaults
+     * (plugin resolver / config) take effect with zero overhead.
+     */
+    private persistenceOptions;
+    /** Delete snapshots and events up to `toSeq` for compaction. */
+    protected deleteHistory(toSeq: number): Promise<void>;
+    /** Read back the persisted events — handy for tests. */
+    protected readEvents(fromSeq?: number, toSeq?: number): Promise<PersistentEvent<Event>[]>;
+}
+//# sourceMappingURL=PersistentActor.d.ts.map

package/dist/persistence/PersistentActor.d.ts.map

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

package/dist/persistence/PersistentActor.js

@@ -0,0 +1,246 @@
+import { Actor } from '../Actor.js';
+import { PersistenceExtensionId } from './PersistenceExtension.js';
+import { decodeEvent, decodeState, encodeEvent, encodeState, } from './migration/Envelope.js';
+/** Convenience: snapshot every N events. */
+export function everyNEvents(n) {
+    if (n <= 0)
+        throw new Error('everyNEvents expects a positive number');
+    return (seq) => seq > 0 && seq % n === 0;
+}
+/**
+ * Classic-style event-sourced actor.  Subclasses override `onCommand`
+ * (which decides what to persist), `onEvent` (pure state update from the
+ * event), and optionally `onRecoveryComplete`.  Commands are automatically
+ * stashed while `persist(...)` is pending, so user code can assume the
+ * state is caught up by the time its callback fires.
+ *
+ *   class AccountActor extends PersistentActor<Cmd, Event, State> {
+ *     readonly persistenceId = 'account-42';
+ *     initialState(): State { return { balance: 0 }; }
+ *     onEvent(state: State, e: Event): State {
+ *       if (e.kind === 'deposited') return { balance: state.balance + e.amount };
+ *       return state;
+ *     }
+ *     onCommand(state: State, cmd: Cmd): void {
+ *       if (cmd.kind === 'deposit') {
+ *         this.persist({ kind: 'deposited', amount: cmd.amount }, (s) => {
+ *           this.sender?.tell({ ok: s.balance });
+ *         });
+ *       }
+ *     }
+ *   }
+ */
+export class PersistentActor extends Actor {
+    /** Called once recovery finishes, with the final replayed state. */
+    onRecoveryComplete(_state) { }
+    /** Called when recovery itself throws.  Default = propagate to supervision. */
+    onRecoveryFailure(reason) { throw reason; }
+    /** Snapshot policy — return true to snapshot the current state. */
+    snapshotPolicy() { return () => false; }
+    /** Optional tags attached to every persisted event (for Persistence Query). */
+    tagsFor(_event) { return undefined; }
+    /**
+     * Optional event adapter for schema evolution.  When defined, every
+     * persisted event is wrapped into a `{ _v, _t, _e }` envelope on the
+     * write path and unwrapped (with up-casting through the adapter) on
+     * the read path.  Recovery is **strict** when an adapter is set: a
+     * raw, non-envelope event in the journal will throw `MigrationError`.
+     * See `src/persistence/migration/`.
+     */
+    eventAdapter() { return undefined; }
+    /**
+     * Optional snapshot adapter — same semantics as `eventAdapter`, but
+     * applied to the `state` blob persisted by the snapshot store.  When
+     * a snapshot adapter is set and a stored snapshot is not an envelope,
+     * recovery throws.
+     */
+    snapshotAdapter() { return undefined; }
+    /**
+     * Per-actor compression — overrides the plugin default for THIS actor's
+     * snapshots.  Stores that don't compress (in-memory, SQLite, Cassandra)
+     * ignore the value.  Returning `undefined` (the default) defers to the
+     * plugin's resolver / configured default.
+     */
+    compression() { return undefined; }
+    /**
+     * Per-actor encryption — overrides the plugin default for THIS actor's
+     * snapshots.  Honoured by stores that encrypt at rest (object-storage);
+     * other stores ignore it.  Used on both the write path (encrypt) and
+     * the read path (derive subkey from master to decrypt).
+     */
+    encryption() { return undefined; }
+    /* ----------------------------- Internal state ---------------------------- */
+    _state;
+    _seq = 0;
+    _journal;
+    _snapshotStore;
+    _recovering = true;
+    /** Set while a persist is in flight — incoming commands get stashed. */
+    _persisting = false;
+    _pendingCallbacks = [];
+    /** Current state — only reliable after recovery. */
+    get state() { return this._state; }
+    /** Highest sequence number reflected in `state`. */
+    get lastSequenceNr() { return this._seq; }
+    /** True while the actor is still replaying history. */
+    get recovering() { return this._recovering; }
+    /* ----------------------------- Lifecycle API ----------------------------- */
+    async preStart() {
+        const ext = this.system.extension(PersistenceExtensionId);
+        this._journal = ext.journal;
+        this._snapshotStore = ext.snapshotStore;
+        try {
+            await this.recover();
+        }
+        catch (e) {
+            this.onRecoveryFailure(e instanceof Error ? e : new Error(String(e)));
+        }
+    }
+    async recover() {
+        this._state = this.initialState();
+        this._seq = 0;
+        const snapAdapter = this.snapshotAdapter();
+        const evAdapter = this.eventAdapter();
+        const persistOpts = this.persistenceOptions();
+        this.log.debug(`[persistence] '${this.persistenceId}' recovery starting`);
+        const snapshot = await this._snapshotStore.loadLatest(this.persistenceId, persistOpts);
+        if (snapshot.isSome()) {
+            const snapSeq = snapshot.value.sequenceNr;
+            // Security: validate the snapshot's claimed seq number BEFORE
+            // trusting it for replay.  An attacker with write access to
+            // the snapshot store (shared bucket, co-tenant, insider) could
+            // craft a snapshot with `sequenceNr = MAX_SAFE_INTEGER` (or
+            // NaN, Infinity, -1, etc.); the old code accepted it and
+            // skipped event replay entirely, recovering with the
+            // attacker's chosen state.  Two-layer check:
+            //   1. seq must be a finite non-negative integer
+            //   2. seq must not exceed what the journal can corroborate
+            if (!Number.isInteger(snapSeq) || snapSeq < 0) {
+                throw new Error(`[persistence] '${this.persistenceId}' snapshot has malformed sequenceNr=${snapSeq} ` +
+                    `— refusing to recover from a corrupted or tampered snapshot`);
+            }
+            // Cross-check against the journal's highest seq: a snapshot that
+            // claims to be AHEAD of the journal but the journal *has*
+            // events for this pid is the classic attack vector — the
+            // attacker pumps the seq sky-high so all real events get
+            // skipped during replay.  An empty journal is fine (legitimate
+            // when state-only snapshots survive a journal compaction or
+            // migration).
+            const journalHigh = await this._journal.highestSeq(this.persistenceId);
+            if (journalHigh > 0 && snapSeq > journalHigh) {
+                throw new Error(`[persistence] '${this.persistenceId}' snapshot claims sequenceNr=${snapSeq} ` +
+                    `but journal's highest seq is ${journalHigh} — refusing to recover from a ` +
+                    `corrupted or tampered snapshot (would silently skip event replay)`);
+            }
+            this._state = decodeState(snapshot.value.state, snapAdapter);
+            this._seq = snapSeq;
+            this.log.debug(`[persistence] '${this.persistenceId}' loaded snapshot @seq=${this._seq}`);
+        }
+        const events = await this._journal.read(this.persistenceId, this._seq + 1);
+        for (const ev of events) {
+            const decoded = decodeEvent(ev.event, evAdapter);
+            this._state = this.onEvent(this._state, decoded);
+            this._seq = ev.sequenceNr;
+        }
+        this.log.debug(`[persistence] '${this.persistenceId}' recovery complete: replayed ${events.length} event(s), seq=${this._seq}`);
+        this._recovering = false;
+        await this.onRecoveryComplete(this._state);
+        // Any commands that arrived during recovery are already stashed by the
+        // ActorCell — release them now so the actor processes them in order.
+        this.context.unstashAll();
+    }
+    async onReceive(message) {
+        if (this._recovering || this._persisting) {
+            this.context.stash();
+            return;
+        }
+        await this.onCommand(this._state, message);
+    }
+    /**
+     * Persist a single event.  The callback runs once the event has been
+     * applied to the state — use it to reply to the sender.  Further
+     * incoming commands are deferred until the callback returns.
+     */
+    async persist(event, cb) {
+        await this.persistAll([event], cb);
+    }
+    /** Persist several events atomically.  Must also be awaited in onCommand. */
+    async persistAll(events, cb) {
+        if (events.length === 0) {
+            await cb?.(this._state);
+            return;
+        }
+        this._persisting = true;
+        try {
+            // Collect tags from the first event — tags are per-event but a single
+            // persistAll keeps them grouped so they share the same tag set.
+            const tags = this.tagsFor(events[0]);
+            // If an event adapter is active, wrap each event into a `{_v,_t,_e}`
+            // envelope before handing it to the journal.  Domain events stay in-
+            // memory unchanged so `onEvent` and `snapshotPolicy` see the original
+            // (current-version) shape.
+            const evAdapter = this.eventAdapter();
+            const wireEvents = evAdapter
+                ? events.map((e) => encodeEvent(e, evAdapter))
+                : events;
+            const written = await this._journal.append(this.persistenceId, wireEvents, this._seq, tags);
+            this.log.debug(`[persistence] '${this.persistenceId}' persisted ${written.length} event(s) → seq=${written[written.length - 1]?.sequenceNr ?? this._seq}`);
+            const policy = this.snapshotPolicy();
+            let shouldSnapshot = false;
+            for (let i = 0; i < written.length; i++) {
+                const pe = written[i];
+                const domainEvent = events[i]; // pre-envelope domain shape
+                this._state = this.onEvent(this._state, domainEvent);
+                this._seq = pe.sequenceNr;
+                if (policy(pe.sequenceNr, this._state, domainEvent))
+                    shouldSnapshot = true;
+            }
+            if (shouldSnapshot)
+                await this.saveSnapshotNow();
+            await cb?.(this._state);
+            // Drain any callbacks queued while we were busy (nested persists).
+            while (this._pendingCallbacks.length > 0) {
+                const next = this._pendingCallbacks.shift();
+                await next(this._state);
+            }
+        }
+        finally {
+            this._persisting = false;
+            // Replay messages stashed during the persist.
+            this.context.unstashAll();
+        }
+    }
+    /** Force a snapshot of the current state. */
+    async saveSnapshot() {
+        return this.saveSnapshotNow();
+    }
+    async saveSnapshotNow() {
+        const snapAdapter = this.snapshotAdapter();
+        const wire = snapAdapter ? encodeState(this._state, snapAdapter) : this._state;
+        // The store is generic over <State>; when we wrap, we store an envelope
+        // and the cast simply re-exposes the typed state to the caller.
+        return this._snapshotStore.save(this.persistenceId, this._seq, wire, this.persistenceOptions());
+    }
+    /**
+     * Build the per-call `PersistenceOptions` from the actor's hooks.
+     * Returns `undefined` when neither hook is set so the store defaults
+     * (plugin resolver / config) take effect with zero overhead.
+     */
+    persistenceOptions() {
+        const compression = this.compression();
+        const encryption = this.encryption();
+        if (!compression && !encryption)
+            return undefined;
+        return { compression, encryption };
+    }
+    /** Delete snapshots and events up to `toSeq` for compaction. */
+    async deleteHistory(toSeq) {
+        await this._snapshotStore.delete(this.persistenceId, toSeq);
+        await this._journal.delete(this.persistenceId, toSeq);
+    }
+    /** Read back the persisted events — handy for tests. */
+    async readEvents(fromSeq = 1, toSeq) {
+        return this._journal.read(this.persistenceId, fromSeq, toSeq);
+    }
+}
+//# sourceMappingURL=PersistentActor.js.map

package/dist/persistence/PersistentActor.js.map

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

package/dist/persistence/ReplicatedEventSourcedActor.d.ts

@@ -0,0 +1,238 @@
+import { Actor } from '../Actor.js';
+import type { Cluster } from '../cluster/Cluster.js';
+import type { Lease } from '../coordination/Lease.js';
+import { type SubscribeAck } from '../cluster/pubsub/Messages.js';
+import type { ReplicaId } from '../crdt/Crdt.js';
+import type { SnapshotPolicy } from './PersistentActor.js';
+import { type ConflictResolver } from './replicated/ConflictResolver.js';
+import { VectorClock, type VectorClockData } from './replicated/VectorClock.js';
+/**
+ * Replicated Event Sourcing — multiple nodes can write events for the
+ * **same** persistenceId concurrently; vector clocks let every replica
+ * recognise the divergent histories and a {@link ConflictResolver}
+ * (default: last-writer-wins) decides how to merge them.
+ *
+ * **Mental model.**  The canonical history at each replica is the
+ * union of every event ever persisted by any replica, sorted in a
+ * deterministic order (by default: `(timestamp, replicaId,
+ * sequenceAtReplica)` via `LastWriterWinsResolver`).  State is the
+ * fold of `onEvent` over that ordered history.  Two replicas that
+ * have received the same set of events compute the same state — that
+ * is the convergence guarantee.
+ *
+ * **Cross-replica delivery** rides on `DistributedPubSub` — each
+ * replica subscribes to a topic derived from its `persistenceId` and
+ * publishes its own persisted events to that same topic.  PubSub
+ * already gives at-least-once gossip-replicated fan-out; the actor
+ * dedupes by `(replica, sequenceAtReplica)`, so re-delivery is
+ * harmless.
+ *
+ * **Local journal**: each replica still appends every event it
+ * **observes** to its local journal (its own + every remote it
+ * receives).  This means on recovery, replaying the local journal
+ * is sufficient to rebuild state — no cross-replica chatter at
+ * startup.  Storage cost: events live N times across N replicas;
+ * fine for the small-write/many-read workloads where Replicated ES
+ * shines.
+ *
+ *   class ReplicatedCounter extends ReplicatedEventSourcedActor<
+ *     Cmd, Event, { value: number }
+ *   > {
+ *     readonly persistenceId = 'counter-1';
+ *     readonly replicaId: string;
+ *     constructor(cluster: Cluster) {
+ *       super(cluster);
+ *       this.replicaId = cluster.selfAddress.toString();
+ *     }
+ *     initialState() { return { value: 0 }; }
+ *     onEvent(s, e) { return { value: s.value + e.amount }; }
+ *     onCommand(s, c) { this.persist({ amount: c.delta }); }
+ *   }
+ *
+ * **Out of scope (for v1):**
+ *   - Cross-DC replication (PubSub gossip is intra-cluster only).
+ *   - Vector-clock garbage collection.  VC entries grow with replicas
+ *     ever seen — fine for a stable cluster, but a node-churn-heavy
+ *     deployment will eventually want compaction.
+ *   - Snapshotting (the local journal is replayed in full on every
+ *     restart).
+ */
+/**
+ * Wire envelope for a single replicated event.  Persisted to the
+ * journal and broadcast over PubSub.  `seqAtReplica` is monotonic
+ * within a replica — the (replica, seqAtReplica) pair uniquely
+ * identifies an event across the whole cluster, which is what we
+ * dedupe on.
+ */
+export interface ReplicatedEventEnvelope<E> {
+    readonly persistenceId: string;
+    readonly replica: ReplicaId;
+    readonly seqAtReplica: number;
+    readonly vc: VectorClockData;
+    readonly timestamp: number;
+    readonly event: E;
+}
+export declare abstract class ReplicatedEventSourcedActor<Cmd, Event, State> extends Actor<Cmd | ReplicatedEventEnvelope<Event>> {
+    readonly cluster: Cluster;
+    abstract readonly persistenceId: string;
+    /** Stable id for this replica.  Default: cluster.selfAddress.toString(). */
+    abstract readonly replicaId: ReplicaId;
+    abstract initialState(): State;
+    abstract onEvent(state: State, event: Event): State;
+    abstract onCommand(state: State, cmd: Cmd): void | Promise<void>;
+    /** Resolver consulted only as the deterministic order comparator. */
+    protected resolver(): ConflictResolver<Event>;
+    /**
+     * How often the underlying DistributedPubSub mediator gossips its
+     * subscription set.  Default 250 ms — tight enough that fresh
+     * actors reach a steady-state cross-replica delivery within a
+     * second, slow enough not to flood small clusters.  Override in
+     * tests for snappier convergence.
+     */
+    protected pubsubGossipIntervalMs(): number;
+    /**
+     * Snapshot policy — return true after applying an event to take a
+     * snapshot of current state.  Default: never snapshot, full journal
+     * is replayed on every restart.
+     *
+     * The `seqNr` argument is the running TOTAL count of events the
+     * actor has observed (own + remote), not just locally-issued ones —
+     * "snapshot every 100 events from any source" is the natural unit.
+     * Re-uses the shared `SnapshotPolicy` helper from `PersistentActor`,
+     * so `everyNEvents(N)` works the same way it does for classic
+     * event-sourced actors.
+     */
+    protected snapshotPolicy(): SnapshotPolicy<State, Event>;
+    /** Recovery hook — called after the local journal has been replayed. */
+    onRecoveryComplete(_state: State): void | Promise<void>;
+    /**
+     * Optional lease (#89) — when this returns a non-null `Lease`, the
+     * actor goes into single-writer mode: only the lease holder may
+     * `persist`, observers passively apply replicated events from
+     * peers.  Default `null` = multi-master semantics (every replica
+     * can persist; vector clocks reconcile concurrent writes).
+     *
+     * Use cases the multi-master default doesn't fit:
+     *
+     *   - **Non-replayable side effects** — charging a credit card,
+     *     emitting an external webhook, sending an email.  The
+     *     framework can't dedupe these for you; restricting writes to
+     *     a single replica ensures the side effect fires once.
+     *   - **Heartbeat / external-rate actors** — N replicas pushing
+     *     beats to a downstream multiplies the rate; the lease binds
+     *     the active emitter to one replica at a time.
+     *
+     * Mechanics: `preStart` calls `lease.acquire()`.  On success the
+     * actor is a holder and persist works normally; on failure it's an
+     * observer (every `persist` call throws).  Lease loss flips the
+     * actor to observer mode and invokes {@link onLeaseLost}; recovery
+     * is restart-driven for this v1.
+     */
+    protected lease(): Lease | null;
+    /**
+     * Hook invoked when this replica unexpectedly loses its lease
+     * (TTL expired, another holder took over, backend failure).  The
+     * actor is already in observer mode by the time this fires — use
+     * the hook to stop downstream side-effect processing, page an
+     * operator, etc.  Default is a no-op.
+     */
+    protected onLeaseLost(_reason: string): void | Promise<void>;
+    private _state;
+    private _vc;
+    /** Strict order: every observed event, deduped, sorted via resolver. */
+    private _events;
+    private _seenIds;
+    private _journal;
+    private _snapshotStore;
+    private _mediator;
+    private _localSeq;
+    /** Journal seq up to which we've absorbed events.  Updated on each
+     *  successful `_appendOne`; persisted as part of the snapshot so
+     *  recovery only re-reads the post-snapshot delta. */
+    private _journalSeq;
+    /** Total observed events count — snapshot policy operates on this. */
+    private _observedCount;
+    /** Guard so concurrent absorbs don't issue overlapping snapshot saves. */
+    private _snapshotInFlight;
+    /** Optional lease this actor holds (or attempted to hold).  See `lease()`. */
+    private _lease;
+    /**
+     * `true` when this replica may issue new `persist` calls.  Without a
+     * lease configured the default is `true` (multi-master); with a
+     * lease, this flips based on `acquire` outcome and `onLost` events.
+     */
+    private _isLeaseHolder;
+    private _leaseUnsubLost;
+    constructor(cluster: Cluster);
+    /** Current state — updated after every event apply. */
+    protected get state(): State;
+    /**
+     * Whether this replica currently holds the configured lease (#89).
+     * Always `true` when no lease is configured (multi-master mode);
+     * dynamic when a lease IS configured — flips to `false` on
+     * `acquire` failure or `onLost` notification.  Use to gate
+     * side-effect logic in `onCommand`.
+     */
+    protected get isLeaseHolder(): boolean;
+    preStart(): Promise<void>;
+    postStop(): void;
+    onReceive(msg: Cmd | ReplicatedEventEnvelope<Event> | SubscribeAck): Promise<void>;
+    /**
+     * Persist a fresh local event.  Increments this replica's VC
+     * component, appends to the journal tagged `replicated-es`, applies
+     * to local state, and broadcasts to peer replicas.
+     *
+     * When a lease is configured (#89) and this replica is NOT the
+     * holder, throws — the actor is in observer mode and writes must
+     * route to the holder.  Users that don't want the throw can gate
+     * on `isLeaseHolder` before calling `persist`.
+     */
+    protected persist(event: Event, cb?: (state: State) => void): Promise<void>;
+    /**
+     * Append exactly one envelope to the local journal.  We read the
+     * current highestSeq inside the same actor mailbox tick so the
+     * `expectedSeq` argument is always accurate — the actor is the
+     * single writer to its own persistenceId, so no other coroutine
+     * can interleave between the read and the append.
+     *
+     * Updates `_journalSeq` so the next snapshot records the
+     * just-appended journal position.
+     */
+    private _appendOne;
+    private _handleRemote;
+    /**
+     * Insert an envelope into the canonical event list, dedupe by
+     * (replica, seqAtReplica), refold state from the divergence point.
+     *
+     * `persistLocally` controls whether we also append the event to
+     * our local journal (true for events received from peers; false
+     * for replays + own broadcasts since those are already on disk).
+     *
+     * `broadcast` controls whether we publish the event to PubSub
+     * (true only for fresh local persists).
+     */
+    private _absorb;
+    /**
+     * Force a snapshot of the current state.  Useful for tests + manual
+     * compaction.  Returns the saved snapshot or `null` if a save was
+     * already in flight.
+     */
+    protected saveSnapshot(): Promise<void>;
+    /**
+     * Triggered by the policy check in `_absorb`.  Fire-and-forget so
+     * the actor's mailbox doesn't block on disk I/O; the in-flight
+     * guard prevents overlapping saves.  Recovery is correct even if a
+     * mid-save crash drops the snapshot — we just fall back to the
+     * previous snapshot or full replay.
+     */
+    private _maybeSaveSnapshot;
+    private _saveSnapshotNow;
+    private _findInsertIndex;
+    private _compare;
+    private _isEnvelope;
+}
+export { LastWriterWinsResolver, CustomMergeResolver } from './replicated/ConflictResolver.js';
+export type { ConflictResolver, ConflictCandidate } from './replicated/ConflictResolver.js';
+export { VectorClock };
+export type { VectorClockData };
+//# sourceMappingURL=ReplicatedEventSourcedActor.d.ts.map

package/dist/persistence/ReplicatedEventSourcedActor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReplicatedEventSourcedActor.d.ts","sourceRoot":"","sources":["../../src/persistence/ReplicatedEventSourcedActor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EACe,KAAK,YAAY,EACtC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AA8BD,8BAAsB,2BAA2B,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,CACjE,SAAQ,KAAK,CAAC,GAAG,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;aAsGvB,OAAO,EAAE,OAAO;IArG5C,QAAQ,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IACxC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAEvC,QAAQ,CAAC,YAAY,IAAI,KAAK;IAC9B,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK;IACnD,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhE,qEAAqE;IACrE,SAAS,CAAC,QAAQ,IAAI,gBAAgB,CAAC,KAAK,CAAC;IAE7C;;;;;;OAMG;IACH,SAAS,CAAC,sBAAsB,IAAI,MAAM;IAE1C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,cAAc,IAAI,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC;IAExD,wEAAwE;IACxE,kBAAkB,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,KAAK,IAAI,KAAK,GAAG,IAAI;IAE/B;;;;;;OAMG;IACH,SAAS,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,GAAG,CAAuB;IAClC,wEAAwE;IACxE,OAAO,CAAC,OAAO,CAA6C;IAC5D,OAAO,CAAC,QAAQ,CAAqB;IAErC,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAwD;IACzE,OAAO,CAAC,SAAS,CAAK;IACtB;;0DAEsD;IACtD,OAAO,CAAC,WAAW,CAAK;IACxB,sEAAsE;IACtE,OAAO,CAAC,cAAc,CAAK;IAC3B,0EAA0E;IAC1E,OAAO,CAAC,iBAAiB,CAAS;IAClC,8EAA8E;IAC9E,OAAO,CAAC,MAAM,CAAsB;IACpC;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,eAAe,CAA6B;gBAExB,OAAO,EAAE,OAAO;IAE5C,uDAAuD;IACvD,SAAS,KAAK,KAAK,IAAI,KAAK,CAAwB;IAEpD;;;;;;OAMG;IACH,SAAS,KAAK,aAAa,IAAI,OAAO,CAAgC;IAEvD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAwG/B,QAAQ,IAAI,IAAI;IAqBV,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,uBAAuB,CAAC,KAAK,CAAC,GAAG,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjG;;;;;;;;;OASG;cACa,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBjF;;;;;;;;;OASG;YACW,UAAU;IAWxB,OAAO,CAAC,aAAa;IAMrB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO;IAwDf;;;;OAIG;cACa,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;YAQZ,gBAAgB;IAoB9B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,WAAW;CAKpB;AAED,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC/F,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,YAAY,EAAE,eAAe,EAAE,CAAC"}