actor-ts 0.9.0

package/dist/persistence/migration/defaultsAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultsAdapter.d.ts","sourceRoot":"","sources":["../../../src/persistence/migration/defaultsAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAiB,eAAe,EAAe,MAAM,cAAc,CAAC;AAG9F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAclG;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAc7G"}

package/dist/persistence/migration/defaultsAdapter.js

@@ -0,0 +1,119 @@
+import { MigrationError } from './Envelope.js';
+/**
+ * Build an `EventAdapter` that handles **purely additive** evolution:
+ * every step from the stored version up to `currentVersion` merges in a
+ * fixed set of default field values for the fields added at that step.
+ *
+ *   // v1 → v2 added a `currency: 'USD' | 'EUR'` field
+ *   const adapter = defaultsAdapter<DepositedV2>({
+ *     manifest: 'BankAccount.Deposited',
+ *     currentVersion: 2,
+ *     defaults: { 1: { currency: 'USD' } },
+ *   });
+ *
+ * Limitations — this helper only handles **adding new fields with constant
+ * defaults**.  Renames, type changes, splits, merges, derived fields all
+ * require a hand-written `MigrationChain`.  When in doubt, write the
+ * chain.
+ */
+export function defaultsAdapter(spec) {
+    validateSpec(spec);
+    const writeVersion = spec.writeVersion ?? spec.currentVersion;
+    return {
+        manifest: () => spec.manifest,
+        toJournal: (event) => ({
+            manifest: spec.manifest,
+            version: writeVersion,
+            payload: writeVersion === spec.currentVersion
+                ? event
+                : downcastByDefaults(event, spec, writeVersion),
+        }),
+        fromJournal: (stored) => upcastByDefaults(stored, spec),
+    };
+}
+/**
+ * Same shape as `defaultsAdapter` but returns a `SnapshotAdapter` —
+ * convenience alias for snapshot / durable-state cases where the same
+ * additive semantics apply to the state record.
+ */
+export function defaultsSnapshotAdapter(spec) {
+    validateSpec(spec);
+    const writeVersion = spec.writeVersion ?? spec.currentVersion;
+    return {
+        manifest: () => spec.manifest,
+        toJournal: (state) => ({
+            manifest: spec.manifest,
+            version: writeVersion,
+            payload: writeVersion === spec.currentVersion
+                ? state
+                : downcastByDefaults(state, spec, writeVersion),
+        }),
+        fromJournal: (stored) => upcastByDefaults(stored, spec),
+    };
+}
+/* ------------------------------ internals -------------------------------- */
+function validateSpec(spec) {
+    if (!Number.isInteger(spec.currentVersion) || spec.currentVersion < 1) {
+        throw new Error(`defaultsAdapter currentVersion must be a positive integer, got ${spec.currentVersion}`);
+    }
+    for (const k of Object.keys(spec.defaults)) {
+        const fromVersion = Number(k);
+        if (!Number.isInteger(fromVersion) || fromVersion < 1) {
+            throw new Error(`defaultsAdapter defaults keys must be positive integers, got '${k}'`);
+        }
+        if (fromVersion >= spec.currentVersion) {
+            throw new Error(`defaultsAdapter has defaults for v${fromVersion} but currentVersion is ${spec.currentVersion} `
+                + `(defaults must apply to versions strictly less than currentVersion)`);
+        }
+    }
+    if (spec.writeVersion !== undefined) {
+        if (!Number.isInteger(spec.writeVersion) || spec.writeVersion < 1) {
+            throw new Error(`defaultsAdapter writeVersion must be a positive integer, got ${spec.writeVersion}`);
+        }
+        if (spec.writeVersion > spec.currentVersion) {
+            throw new Error(`defaultsAdapter writeVersion ${spec.writeVersion} cannot exceed currentVersion ${spec.currentVersion}`);
+        }
+        // Every step in (writeVersion, currentVersion] must have a defaults
+        // entry — that's where we know which fields to strip on write.
+        for (let v = spec.writeVersion; v < spec.currentVersion; v++) {
+            if (!spec.defaults[v]) {
+                throw new Error(`defaultsAdapter writeVersion=${spec.writeVersion} requires defaults entries for every `
+                    + `step on the path to currentVersion=${spec.currentVersion}; missing defaults[${v}]`);
+            }
+        }
+    }
+}
+function upcastByDefaults(stored, spec) {
+    if (stored.manifest !== spec.manifest) {
+        throw new MigrationError(`manifest mismatch: defaultsAdapter is for '${spec.manifest}', got '${stored.manifest}'`, stored.manifest, stored.version);
+    }
+    if (stored.version > spec.currentVersion) {
+        throw new MigrationError(`cannot downgrade '${stored.manifest}' from v${stored.version} to v${spec.currentVersion}`, stored.manifest, stored.version);
+    }
+    let payload = stored.payload;
+    for (let v = stored.version; v < spec.currentVersion; v++) {
+        const fill = spec.defaults[v];
+        if (fill)
+            payload = { ...fill, ...payload };
+    }
+    return payload;
+}
+/**
+ * Inverse of {@link upcastByDefaults} — strip the fields added at
+ * each step in `(targetVersion, currentVersion]`.  Used on the write
+ * path when `writeVersion < currentVersion` (#7) so the emitted
+ * payload has exactly the shape an older reader expects.
+ */
+function downcastByDefaults(current, spec, targetVersion) {
+    let payload = { ...current };
+    for (let v = spec.currentVersion - 1; v >= targetVersion; v--) {
+        const fields = spec.defaults[v];
+        if (!fields)
+            continue;
+        for (const key of Object.keys(fields)) {
+            delete payload[key];
+        }
+    }
+    return payload;
+}
+//# sourceMappingURL=defaultsAdapter.js.map

package/dist/persistence/migration/defaultsAdapter.js.map

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

package/dist/persistence/migration/index.d.ts

@@ -0,0 +1,18 @@
+export type { EventAdapter, SnapshotAdapter, StateAdapter, JournalEnvelope, StoredFrame, OutboundFrame, } from './Adapter.js';
+export { MigrationError, isEnvelope, encodeEvent, decodeEvent, encodeState, decodeState, } from './Envelope.js';
+export { MigrationChain } from './MigrationChain.js';
+export type { MigrationStep, DowncastStep } from './MigrationChain.js';
+export { defaultsAdapter, defaultsSnapshotAdapter, } from './defaultsAdapter.js';
+export type { DefaultsAdapterSpec } from './defaultsAdapter.js';
+export { migratingAdapter, migratingSnapshotAdapter, } from './migratingAdapter.js';
+export { wrapEventAsEnvelope, wrapStateAsEnvelope, migrateInMemoryJournal, migrateSnapshotStore, formatMigrationResult, } from './wrapLegacy.js';
+export type { MigrationResult } from './wrapLegacy.js';
+export { jsonCodec, zodCodec, composeCodecs } from './Codec.js';
+export type { Codec, ParserLike } from './Codec.js';
+export { validatedEventAdapter, validatedSnapshotAdapter, } from './validatedAdapter.js';
+export type { ValidatedAdapterOptions } from './validatedAdapter.js';
+export { InMemorySchemaRegistry } from './SchemaRegistry.js';
+export type { SchemaRegistry, SchemaRegistration, SchemaDescriptor, } from './SchemaRegistry.js';
+export { migrateBetweenJournals, migrateBetweenSnapshotStores, InMemoryMigrationProgressStore, } from './journalMigration.js';
+export type { MigrateJournalsOptions, MigrateJournalsResult, MigrateSnapshotStoresOptions, MigrateSnapshotStoresResult, MigrationProgress, MigrationProgressStore, } from './journalMigration.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/persistence/migration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/persistence/migration/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EACL,eAAe,EACf,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,YAAY,EACV,cAAc,EACd,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}

package/dist/persistence/migration/index.js

@@ -0,0 +1,12 @@
+export { MigrationError, isEnvelope, encodeEvent, decodeEvent, encodeState, decodeState, } from './Envelope.js';
+export { MigrationChain } from './MigrationChain.js';
+export { defaultsAdapter, defaultsSnapshotAdapter, } from './defaultsAdapter.js';
+export { migratingAdapter, migratingSnapshotAdapter, } from './migratingAdapter.js';
+export { wrapEventAsEnvelope, wrapStateAsEnvelope, migrateInMemoryJournal, migrateSnapshotStore, formatMigrationResult, } from './wrapLegacy.js';
+// #6 — pluggable codec + in-process schema registry.
+export { jsonCodec, zodCodec, composeCodecs } from './Codec.js';
+export { validatedEventAdapter, validatedSnapshotAdapter, } from './validatedAdapter.js';
+export { InMemorySchemaRegistry } from './SchemaRegistry.js';
+// #87 — journal-to-journal + snapshot-store-to-snapshot-store copy.
+export { migrateBetweenJournals, migrateBetweenSnapshotStores, InMemoryMigrationProgressStore, } from './journalMigration.js';
+//# sourceMappingURL=index.js.map

package/dist/persistence/migration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/persistence/migration/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,cAAc,EACd,UAAU,EACV,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,eAAe,EACf,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,qDAAqD;AACrD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAO7D,oEAAoE;AACpE,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC"}

package/dist/persistence/migration/journalMigration.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Generic journal-to-journal and snapshot-store-to-snapshot-store copy
+ * helpers (#87) — for the common operations of "we're switching from
+ * SQLite to Cassandra in production" or "rehydrate test fixtures from
+ * a recorded production journal" or "snapshot a smoke-test bucket
+ * before destroying it".
+ *
+ * Distinct from {@link wrapLegacy}'s helpers — those rewrite events in
+ * place to wrap them in envelopes; these COPY from one backend to
+ * another, optionally transforming as they go.  An eventTransform hook
+ * lets you piggyback a schema migration on the copy (one less pass over
+ * the data).
+ *
+ * Resumability: the optional {@link MigrationProgressStore} lets a
+ * crashed sweep pick up where it left off — see `InMemoryMigrationProgress
+ * Store` for the simplest implementation and the docstring on
+ * {@link migrateBetweenJournals} for the semantics.
+ */
+import type { Journal } from '../Journal.js';
+import type { SnapshotStore } from '../SnapshotStore.js';
+import type { PersistentEvent } from '../JournalTypes.js';
+/**
+ * Crash-resume hook for long-running migrations.  The helper calls
+ * `load()` once at start (to skip already-completed pids), and `save()`
+ * after each pid finishes.  Implementations write to a small KV store
+ * (file, Redis, SQLite single-row, …).
+ */
+export interface MigrationProgressStore {
+    load(): Promise<MigrationProgress>;
+    save(state: MigrationProgress): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface MigrationProgress {
+    /** Pids the helper has already finished — used to skip them on resume. */
+    readonly completed: ReadonlyArray<string>;
+}
+/**
+ * Simple in-process implementation, useful for tests and for short-
+ * lived runs where progress only needs to survive within one process.
+ * For long-running sweeps that should survive a process crash, write a
+ * file-backed variant (a JSON dump of `{completed: [...]}` works).
+ */
+export declare class InMemoryMigrationProgressStore implements MigrationProgressStore {
+    private state;
+    load(): Promise<MigrationProgress>;
+    save(state: MigrationProgress): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface MigrateJournalsOptions<E = unknown> {
+    /**
+     * Per-event transform.  Default: pass through unchanged.  Use this
+     * to piggyback a schema migration (envelope wrap, V1→V2 rename, …)
+     * on the same pass that copies the data — saves an extra sweep.
+     */
+    readonly eventTransform?: (e: PersistentEvent<E>) => PersistentEvent<E>;
+    /** Resume-state.  See {@link MigrationProgressStore}. */
+    readonly progress?: MigrationProgressStore;
+    /** Optional progress hook called once per pid after a successful copy. */
+    readonly onProgress?: (e: {
+        pid: string;
+        events: number;
+        idx: number;
+        total: number;
+    }) => void;
+    /**
+     * Pids to copy.  Default: every pid `source.persistenceIds()`
+     * returns.  Subset useful for sharded migrations (e.g. one worker
+     * per shard).
+     */
+    readonly pids?: ReadonlyArray<string>;
+    /**
+     * When true, skip pids that already exist in `target` (any non-zero
+     * highestSeq).  Default: false — append from `target.highestSeq + 1`
+     * onward, useful for resuming an interrupted copy mid-pid.
+     */
+    readonly skipExistingPids?: boolean;
+}
+export interface MigrateJournalsResult {
+    /** Pids inspected (incl. skipped). */
+    readonly pidsInspected: number;
+    /** Pids the helper actually wrote events for. */
+    readonly pidsWritten: number;
+    /** Pids fully skipped because they were already in `completed`. */
+    readonly pidsSkippedAlreadyDone: number;
+    /** Pids skipped because of `skipExistingPids: true` and target had data. */
+    readonly pidsSkippedExistingTarget: number;
+    /** Total events written to the target. */
+    readonly eventsWritten: number;
+}
+/**
+ * Copy every event from `source` to `target`, in pid+seq order.
+ *
+ * **Idempotent resume.**  For each pid the helper reads `target.highestSeq`
+ * first; only events with strictly higher seq are read from `source` and
+ * appended.  A run that completed pid-A and crashed mid-pid-B can be
+ * re-run safely — pid-A's count is `0` writes, pid-B picks up where it
+ * left off.
+ *
+ * **Concurrency.**  Single-writer.  Don't run two `migrateBetweenJournals`
+ * for the same `target` simultaneously — the `expectedSeq` race would
+ * surface as `JournalConcurrencyError`.
+ *
+ * **Tags.**  Each event's `tags` field is preserved via per-event
+ * `append` calls (one event per call to keep the source's tag layout
+ * exact).  Trade-off: more round-trips than a batched copy, but tag
+ * fidelity is what most migrations care about.
+ *
+ *   await migrateBetweenJournals(sqliteSource, cassandraTarget, {
+ *     eventTransform: (e) => ({
+ *       ...e,
+ *       event: oldShapeToNew(e.event),
+ *     }),
+ *     onProgress: (p) => console.log(
+ *       `[${p.idx}/${p.total}] ${p.pid}: ${p.events} events`),
+ *   });
+ */
+export declare function migrateBetweenJournals<E = unknown>(source: Journal, target: Journal, opts?: MigrateJournalsOptions<E>): Promise<MigrateJournalsResult>;
+export interface MigrateSnapshotStoresOptions<S = unknown> {
+    /** Per-snapshot transform; default: pass through. */
+    readonly stateTransform?: (s: S) => S;
+    /** Set of pids to copy; default: caller must supply (no enumeration on snapshot stores). */
+    readonly pids: ReadonlyArray<string>;
+    readonly progress?: MigrationProgressStore;
+    readonly onProgress?: (e: {
+        pid: string;
+        idx: number;
+        total: number;
+        copied: boolean;
+    }) => void;
+    /** Skip pids whose target already has a latest snapshot. */
+    readonly skipExistingPids?: boolean;
+}
+export interface MigrateSnapshotStoresResult {
+    readonly pidsInspected: number;
+    readonly pidsCopied: number;
+    readonly pidsEmpty: number;
+    readonly pidsSkippedAlreadyDone: number;
+    readonly pidsSkippedExistingTarget: number;
+}
+/**
+ * Copy the LATEST snapshot for each `pid` from `source` to `target`.
+ *
+ * Snapshot stores don't expose a `persistenceIds()` enumeration (the
+ * shape varies wildly across backends), so the caller hands in the pid
+ * list — typically `await sourceJournal.persistenceIds()` when running
+ * a paired journal + snapshot migration.
+ *
+ * Historical snapshots aren't copied — only the most recent one per
+ * pid.  Cold-start recovery only ever reads the latest plus events
+ * since, so the older history isn't load-bearing.  If you need
+ * historical snapshots too, run the helper repeatedly with the source
+ * narrowing on each pass (loadBefore + manual save).
+ */
+export declare function migrateBetweenSnapshotStores<S = unknown>(source: SnapshotStore, target: SnapshotStore, opts: MigrateSnapshotStoresOptions<S>): Promise<MigrateSnapshotStoresResult>;
+//# sourceMappingURL=journalMigration.d.ts.map

package/dist/persistence/migration/journalMigration.d.ts.map

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

package/dist/persistence/migration/journalMigration.js

@@ -0,0 +1,149 @@
+/**
+ * Simple in-process implementation, useful for tests and for short-
+ * lived runs where progress only needs to survive within one process.
+ * For long-running sweeps that should survive a process crash, write a
+ * file-backed variant (a JSON dump of `{completed: [...]}` works).
+ */
+export class InMemoryMigrationProgressStore {
+    state = { completed: [] };
+    async load() { return { completed: [...this.state.completed] }; }
+    async save(state) { this.state = { completed: [...state.completed] }; }
+    async clear() { this.state = { completed: [] }; }
+}
+/**
+ * Copy every event from `source` to `target`, in pid+seq order.
+ *
+ * **Idempotent resume.**  For each pid the helper reads `target.highestSeq`
+ * first; only events with strictly higher seq are read from `source` and
+ * appended.  A run that completed pid-A and crashed mid-pid-B can be
+ * re-run safely — pid-A's count is `0` writes, pid-B picks up where it
+ * left off.
+ *
+ * **Concurrency.**  Single-writer.  Don't run two `migrateBetweenJournals`
+ * for the same `target` simultaneously — the `expectedSeq` race would
+ * surface as `JournalConcurrencyError`.
+ *
+ * **Tags.**  Each event's `tags` field is preserved via per-event
+ * `append` calls (one event per call to keep the source's tag layout
+ * exact).  Trade-off: more round-trips than a batched copy, but tag
+ * fidelity is what most migrations care about.
+ *
+ *   await migrateBetweenJournals(sqliteSource, cassandraTarget, {
+ *     eventTransform: (e) => ({
+ *       ...e,
+ *       event: oldShapeToNew(e.event),
+ *     }),
+ *     onProgress: (p) => console.log(
+ *       `[${p.idx}/${p.total}] ${p.pid}: ${p.events} events`),
+ *   });
+ */
+export async function migrateBetweenJournals(source, target, opts = {}) {
+    const allPids = opts.pids ?? await source.persistenceIds();
+    const progress = opts.progress;
+    const completed = new Set(progress ? (await progress.load()).completed : []);
+    const transform = opts.eventTransform ?? ((e) => e);
+    const result = {
+        pidsInspected: 0,
+        pidsWritten: 0,
+        pidsSkippedAlreadyDone: 0,
+        pidsSkippedExistingTarget: 0,
+        eventsWritten: 0,
+    };
+    for (let idx = 0; idx < allPids.length; idx++) {
+        const pid = allPids[idx];
+        result.pidsInspected += 1;
+        if (completed.has(pid)) {
+            result.pidsSkippedAlreadyDone += 1;
+            continue;
+        }
+        const targetHigh = await target.highestSeq(pid);
+        if (opts.skipExistingPids && targetHigh > 0) {
+            result.pidsSkippedExistingTarget += 1;
+            // Treat as completed for future resume runs.
+            completed.add(pid);
+            if (progress)
+                await progress.save({ completed: [...completed] });
+            continue;
+        }
+        // Source events strictly above what's already in the target.
+        const sourceEvents = await source.read(pid, targetHigh + 1);
+        if (sourceEvents.length > 0) {
+            let expected = targetHigh;
+            for (const se of sourceEvents) {
+                const transformed = transform(se);
+                await target.append(pid, [transformed.event], expected, transformed.tags);
+                expected += 1;
+                result.eventsWritten += 1;
+            }
+            result.pidsWritten += 1;
+        }
+        completed.add(pid);
+        if (progress)
+            await progress.save({ completed: [...completed] });
+        opts.onProgress?.({
+            pid, events: sourceEvents.length, idx, total: allPids.length,
+        });
+    }
+    return result;
+}
+/**
+ * Copy the LATEST snapshot for each `pid` from `source` to `target`.
+ *
+ * Snapshot stores don't expose a `persistenceIds()` enumeration (the
+ * shape varies wildly across backends), so the caller hands in the pid
+ * list — typically `await sourceJournal.persistenceIds()` when running
+ * a paired journal + snapshot migration.
+ *
+ * Historical snapshots aren't copied — only the most recent one per
+ * pid.  Cold-start recovery only ever reads the latest plus events
+ * since, so the older history isn't load-bearing.  If you need
+ * historical snapshots too, run the helper repeatedly with the source
+ * narrowing on each pass (loadBefore + manual save).
+ */
+export async function migrateBetweenSnapshotStores(source, target, opts) {
+    const progress = opts.progress;
+    const completed = new Set(progress ? (await progress.load()).completed : []);
+    const transform = opts.stateTransform ?? ((s) => s);
+    const result = {
+        pidsInspected: 0,
+        pidsCopied: 0,
+        pidsEmpty: 0,
+        pidsSkippedAlreadyDone: 0,
+        pidsSkippedExistingTarget: 0,
+    };
+    for (let idx = 0; idx < opts.pids.length; idx++) {
+        const pid = opts.pids[idx];
+        result.pidsInspected += 1;
+        if (completed.has(pid)) {
+            result.pidsSkippedAlreadyDone += 1;
+            continue;
+        }
+        if (opts.skipExistingPids) {
+            const existing = await target.loadLatest(pid);
+            if (!existing.isNone()) {
+                result.pidsSkippedExistingTarget += 1;
+                completed.add(pid);
+                if (progress)
+                    await progress.save({ completed: [...completed] });
+                continue;
+            }
+        }
+        const latest = await source.loadLatest(pid);
+        if (latest.isNone()) {
+            result.pidsEmpty += 1;
+        }
+        else {
+            const snap = latest.value;
+            await target.save(pid, snap.sequenceNr, transform(snap.state));
+            result.pidsCopied += 1;
+        }
+        completed.add(pid);
+        if (progress)
+            await progress.save({ completed: [...completed] });
+        opts.onProgress?.({
+            pid, idx, total: opts.pids.length, copied: !latest.isNone(),
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=journalMigration.js.map

package/dist/persistence/migration/journalMigration.js.map

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

package/dist/persistence/migration/migratingAdapter.d.ts

@@ -0,0 +1,43 @@
+import type { EventAdapter, SnapshotAdapter } from './Adapter.js';
+import type { MigrationChain } from './MigrationChain.js';
+/**
+ * Build an {@link EventAdapter} from a {@link MigrationChain} —
+ * convenience for the common case where one chain handles both
+ * directions (upcast on read, optional downcast on write).
+ *
+ * `writeVersion` (defaults to the chain's `currentVersion`) is the
+ * version actually written to the journal.  Set it lower than
+ * `currentVersion` during a rolling deployment so v2 nodes keep
+ * emitting v1 events for as long as v1 readers are still in the
+ * cluster (#7).  When `writeVersion < currentVersion`, the chain
+ * **must** have downcasters covering every step on the path
+ * `currentVersion → writeVersion` — otherwise `toJournal` throws.
+ *
+ *   const chain = MigrationChain.for<DepositedV2>('Deposited', 2)
+ *     .add({ fromVersion: 1, toVersion: 2,
+ *            upcast: (v: DepositedV1): DepositedV2 => ({ ...v, currency: 'USD' }) })
+ *     .addDown({ fromVersion: 2, toVersion: 1,
+ *                downcast: (v: DepositedV2): DepositedV1 => {
+ *                  const { currency, ...rest } = v; void currency; return rest as DepositedV1;
+ *                } });
+ *
+ *   // Phase 1 of rollout — write v1 still, read both:
+ *   const phase1 = migratingAdapter(chain, { writeVersion: 1 });
+ *
+ *   // Phase 2 once every reader is on the new code — flip:
+ *   const phase2 = migratingAdapter(chain);   // writeVersion = currentVersion = 2
+ */
+export declare function migratingAdapter<E>(chain: MigrationChain<E>, opts?: {
+    readonly writeVersion?: number;
+}): EventAdapter<E, unknown>;
+/**
+ * Same as {@link migratingAdapter} but returns a {@link SnapshotAdapter}
+ * — useful when the same MigrationChain governs both events and the
+ * snapshot of derived state.  Snapshots usually don't need a rolling
+ * `writeVersion` (snapshots are produced by one writer, the actor),
+ * but the helper is symmetric for the user's convenience.
+ */
+export declare function migratingSnapshotAdapter<S>(chain: MigrationChain<S>, opts?: {
+    readonly writeVersion?: number;
+}): SnapshotAdapter<S, unknown>;
+//# sourceMappingURL=migratingAdapter.d.ts.map

package/dist/persistence/migration/migratingAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migratingAdapter.d.ts","sourceRoot":"","sources":["../../../src/persistence/migration/migratingAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAiB,eAAe,EAAe,MAAM,cAAc,CAAC;AAC9F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,IAAI,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAgB1B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EACxB,IAAI,GAAE;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,CAgB7B"}

package/dist/persistence/migration/migratingAdapter.js

@@ -0,0 +1,65 @@
+/**
+ * Build an {@link EventAdapter} from a {@link MigrationChain} —
+ * convenience for the common case where one chain handles both
+ * directions (upcast on read, optional downcast on write).
+ *
+ * `writeVersion` (defaults to the chain's `currentVersion`) is the
+ * version actually written to the journal.  Set it lower than
+ * `currentVersion` during a rolling deployment so v2 nodes keep
+ * emitting v1 events for as long as v1 readers are still in the
+ * cluster (#7).  When `writeVersion < currentVersion`, the chain
+ * **must** have downcasters covering every step on the path
+ * `currentVersion → writeVersion` — otherwise `toJournal` throws.
+ *
+ *   const chain = MigrationChain.for<DepositedV2>('Deposited', 2)
+ *     .add({ fromVersion: 1, toVersion: 2,
+ *            upcast: (v: DepositedV1): DepositedV2 => ({ ...v, currency: 'USD' }) })
+ *     .addDown({ fromVersion: 2, toVersion: 1,
+ *                downcast: (v: DepositedV2): DepositedV1 => {
+ *                  const { currency, ...rest } = v; void currency; return rest as DepositedV1;
+ *                } });
+ *
+ *   // Phase 1 of rollout — write v1 still, read both:
+ *   const phase1 = migratingAdapter(chain, { writeVersion: 1 });
+ *
+ *   // Phase 2 once every reader is on the new code — flip:
+ *   const phase2 = migratingAdapter(chain);   // writeVersion = currentVersion = 2
+ */
+export function migratingAdapter(chain, opts = {}) {
+    const writeVersion = opts.writeVersion ?? chain.currentVersion;
+    if (!Number.isInteger(writeVersion) || writeVersion < 1) {
+        throw new Error(`migratingAdapter writeVersion must be a positive integer, got ${writeVersion}`);
+    }
+    if (writeVersion > chain.currentVersion) {
+        throw new Error(`migratingAdapter writeVersion ${writeVersion} cannot exceed `
+            + `chain.currentVersion ${chain.currentVersion}`);
+    }
+    return {
+        manifest: () => chain.manifest,
+        toJournal: (event) => chain.toJournalAt(event, writeVersion),
+        fromJournal: (stored) => chain.upcast(stored),
+    };
+}
+/**
+ * Same as {@link migratingAdapter} but returns a {@link SnapshotAdapter}
+ * — useful when the same MigrationChain governs both events and the
+ * snapshot of derived state.  Snapshots usually don't need a rolling
+ * `writeVersion` (snapshots are produced by one writer, the actor),
+ * but the helper is symmetric for the user's convenience.
+ */
+export function migratingSnapshotAdapter(chain, opts = {}) {
+    const writeVersion = opts.writeVersion ?? chain.currentVersion;
+    if (!Number.isInteger(writeVersion) || writeVersion < 1) {
+        throw new Error(`migratingSnapshotAdapter writeVersion must be a positive integer, got ${writeVersion}`);
+    }
+    if (writeVersion > chain.currentVersion) {
+        throw new Error(`migratingSnapshotAdapter writeVersion ${writeVersion} cannot exceed `
+            + `chain.currentVersion ${chain.currentVersion}`);
+    }
+    return {
+        manifest: () => chain.manifest,
+        toJournal: (state) => chain.toJournalAt(state, writeVersion),
+        fromJournal: (stored) => chain.upcast(stored),
+    };
+}
+//# sourceMappingURL=migratingAdapter.js.map

package/dist/persistence/migration/migratingAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migratingAdapter.js","sourceRoot":"","sources":["../../../src/persistence/migration/migratingAdapter.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAwB,EACxB,OAA2C,EAAE;IAE7C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,KAAK,CAAC,cAAc,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,iEAAiE,YAAY,EAAE,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,YAAY,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,iCAAiC,YAAY,iBAAiB;cAC5D,wBAAwB,KAAK,CAAC,cAAc,EAAE,CACjD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ;QAC9B,SAAS,EAAE,CAAC,KAAQ,EAA0B,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC;QACvF,WAAW,EAAE,CAAC,MAAmB,EAAK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;KAC9D,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAwB,EACxB,OAA2C,EAAE;IAE7C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,KAAK,CAAC,cAAc,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,yEAAyE,YAAY,EAAE,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,YAAY,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,yCAAyC,YAAY,iBAAiB;cACpE,wBAAwB,KAAK,CAAC,cAAc,EAAE,CACjD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ;QAC9B,SAAS,EAAE,CAAC,KAAQ,EAA0B,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,YAAY,CAAC;QACvF,WAAW,EAAE,CAAC,MAAmB,EAAK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;KAC9D,CAAC;AACJ,CAAC"}