actor-ts 0.9.0

package/dist/persistence/migration/Envelope.js

@@ -0,0 +1,79 @@
+/**
+ * Wire-format helpers for the `_v / _t / _e` JSON envelope used by
+ * `PersistentActor` and `DurableStateActor` when an adapter is active.
+ *
+ * The envelope rides inside the existing `event` / `state` JSON slot of
+ * the journal / snapshot store, so no backend (InMemory, SQLite,
+ * Cassandra, object-storage) needs schema changes.  The magic keys are
+ * `_v`, `_t`, `_e` — underscore-prefixed to make accidental collisions
+ * with domain types vanishingly unlikely.
+ */
+/** Raised when adapter-driven decoding hits a malformed/legacy payload. */
+export class MigrationError extends Error {
+    manifest;
+    version;
+    constructor(message, manifest, version) {
+        super(message);
+        this.manifest = manifest;
+        this.version = version;
+        this.name = 'MigrationError';
+    }
+}
+/** True iff `o` looks like a `JournalEnvelope`. */
+export function isEnvelope(o) {
+    if (typeof o !== 'object' || o === null)
+        return false;
+    const env = o;
+    return typeof env._v === 'number'
+        && typeof env._t === 'string'
+        && '_e' in env;
+}
+/* ------------------------------ events ----------------------------------- */
+/** Wrap a domain event into an envelope using the supplied adapter. */
+export function encodeEvent(event, adapter) {
+    const frame = adapter.toJournal(event);
+    return { _v: frame.version, _t: frame.manifest, _e: frame.payload };
+}
+/**
+ * Decode a value read from the journal.  When `adapter` is undefined the
+ * caller has not opted into the migration system — the value is returned
+ * as-is and is assumed to be a raw domain event.  When `adapter` is
+ * defined, the value MUST be an envelope; otherwise a `MigrationError` is
+ * raised (strict mode — see plan §1).
+ */
+export function decodeEvent(stored, adapter) {
+    if (!adapter)
+        return stored;
+    if (!isEnvelope(stored)) {
+        throw new MigrationError('expected envelope, got raw payload — eventAdapter is configured but the journal '
+            + 'contains an event without _v/_t/_e markers.  Either run a one-shot migration '
+            + 'script to wrap legacy events, or remove eventAdapter() until you have envelopes '
+            + 'on disk.');
+    }
+    return adapter.fromJournal(toFrame(stored));
+}
+/* ----------------------------- snapshots --------------------------------- */
+/** Wrap a snapshot state into an envelope using the supplied adapter. */
+export function encodeState(state, adapter) {
+    const frame = adapter.toJournal(state);
+    return { _v: frame.version, _t: frame.manifest, _e: frame.payload };
+}
+/**
+ * Decode a state read from the snapshot store / durable-state store.
+ * Same strict semantics as `decodeEvent`.
+ */
+export function decodeState(stored, adapter) {
+    if (!adapter)
+        return stored;
+    if (!isEnvelope(stored)) {
+        throw new MigrationError('expected envelope, got raw payload — a state/snapshot adapter is configured but '
+            + 'the persisted state has no _v/_t/_e markers.  Wrap legacy state with a one-shot '
+            + 'migration script or drop the adapter until envelopes are on disk.');
+    }
+    return adapter.fromJournal(toFrame(stored));
+}
+/* ------------------------------ internal --------------------------------- */
+function toFrame(env) {
+    return { manifest: env._t, version: env._v, payload: env._e };
+}
+//# sourceMappingURL=Envelope.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Envelope.js","sourceRoot":"","sources":["../../../src/persistence/migration/Envelope.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGrB;IACA;IAHlB,YACE,OAAe,EACC,QAAiB,EACjB,OAAgB;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,aAAQ,GAAR,QAAQ,CAAS;QACjB,YAAO,GAAP,OAAO,CAAS;QAGhC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,UAAU,UAAU,CAAC,CAAU;IACnC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,GAAG,GAAG,CAA4B,CAAC;IACzC,OAAO,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;WAC1B,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;WAC1B,IAAI,IAAI,GAAG,CAAC;AACrB,CAAC;AAED,+EAA+E;AAE/E,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAO,KAAQ,EAAE,OAA2B;IACrE,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAI,MAAe,EAAE,OAAoC;IAClF,IAAI,CAAC,OAAO;QAAE,OAAO,MAAW,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CACtB,kFAAkF;cAChF,+EAA+E;cAC/E,kFAAkF;cAClF,UAAU,CACb,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,+EAA+E;AAE/E,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAO,KAAQ,EAAE,OAA8B;IACxE,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAI,MAAe,EAAE,OAAuC;IACrF,IAAI,CAAC,OAAO;QAAE,OAAO,MAAW,CAAC;IACjC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,cAAc,CACtB,kFAAkF;cAChF,kFAAkF;cAClF,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,+EAA+E;AAE/E,SAAS,OAAO,CAAC,GAAoB;IACnC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1,100 @@
+import type { OutboundFrame, StoredFrame } from './Adapter.js';
+/**
+ * One step in an upcaster pipeline — a pure function that maps a payload
+ * at version `fromVersion` to one at version `toVersion`.  Steps are
+ * normally consecutive (`fromVersion + 1 === toVersion`); larger jumps
+ * are allowed but rare.
+ */
+export interface MigrationStep<From = unknown, To = unknown> {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    upcast(from: From): To;
+}
+/**
+ * Inverse of {@link MigrationStep} — maps a current-shape payload back
+ * to an older shape on the **write** path (#7).  Used during rolling
+ * deployments where v2 nodes need to keep emitting v1 events for as
+ * long as v1 readers are still in the cluster.  Steps move backward:
+ * `fromVersion > toVersion`, typically `toVersion = fromVersion - 1`.
+ */
+export interface DowncastStep<From = unknown, To = unknown> {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    downcast(from: From): To;
+}
+/**
+ * Linear chain of `MigrationStep`s for a single manifest, terminating at
+ * a `currentVersion` known to the running code.  On `upcast(stored)`, the
+ * chain locates the step starting at `stored.version` and applies steps
+ * forward until it reaches `currentVersion`.
+ *
+ * The chain is intentionally narrow: one manifest, one current version,
+ * one linear path.  Multiple types → multiple chains, kept inside an
+ * `EventAdapter.fromJournal` switch by manifest.
+ *
+ *   const chain = MigrationChain.for<DepositedV2>('BankAccount.Deposited', 2)
+ *     .add({ fromVersion: 1, toVersion: 2,
+ *            upcast: (v: DepositedV1): DepositedV2 => ({ ...v, currency: 'USD' }) });
+ *
+ * `chain.upcast({ manifest: 'BankAccount.Deposited', version: 1, payload })`
+ * returns a `DepositedV2`.
+ *
+ * Errors:
+ *   - manifest mismatch → `MigrationError`
+ *   - `stored.version > currentVersion` (downgrade) → `MigrationError`
+ *   - no step available at the current cursor before `currentVersion` is
+ *     reached (chain gap) → `MigrationError` with the gap printed.
+ */
+export declare class MigrationChain<Current> {
+    private readonly _manifest;
+    private readonly _currentVersion;
+    private readonly steps;
+    private readonly downsteps;
+    private constructor();
+    /** Build an empty chain for `manifest` whose latest known version is `currentVersion`. */
+    static for<C>(manifest: string, currentVersion: number): MigrationChain<C>;
+    /** Append an upcaster.  Returns `this` for chaining. */
+    add<F, T>(step: MigrationStep<F, T>): MigrationChain<Current>;
+    /**
+     * Append a downcaster — the inverse of {@link MigrationStep}.
+     * Required when the actor is going to be configured with a
+     * `writeVersion` lower than `currentVersion` (#7).  Steps move
+     * **backward**: `fromVersion > toVersion`.
+     *
+     *   chain.addDown({
+     *     fromVersion: 2, toVersion: 1,
+     *     downcast: (e: DepositedV2): DepositedV1 => {
+     *       const { currency, ...rest } = e; void currency; return rest;
+     *     },
+     *   });
+     */
+    addDown<F, T>(step: DowncastStep<F, T>): MigrationChain<Current>;
+    /** Manifest this chain is bound to. */
+    get manifest(): string;
+    /** Latest version this chain knows how to produce. */
+    get currentVersion(): number;
+    /** Apply the chain to a stored frame, returning a current-version value. */
+    upcast(stored: StoredFrame): Current;
+    /**
+     * Convert a current-shape value down to `targetVersion` for a
+     * write-with-old-shape rolling deploy (#7).  Walks the registered
+     * downcasters from `currentVersion` toward `targetVersion`.
+     *
+     * Errors:
+     *   - `targetVersion > currentVersion` → `MigrationError` (we're
+     *     already at or above the target; user should call `toJournalAt`
+     *     with `version: currentVersion`).
+     *   - `targetVersion < 1` → `MigrationError`.
+     *   - chain gap (no downcaster for the current cursor) →
+     *     `MigrationError` with the missing step printed.
+     */
+    downcast(current: Current, targetVersion: number): unknown;
+    /**
+     * Build an `OutboundFrame` for the write path at `writeVersion`
+     * (defaults to `currentVersion`).  Convenience that combines the
+     * downcast + frame-shape — exactly what `migratingAdapter` calls
+     * from its `toJournal`.
+     */
+    toJournalAt(current: Current, writeVersion?: number): OutboundFrame;
+}
+//# sourceMappingURL=MigrationChain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MigrationChain.d.ts","sourceRoot":"","sources":["../../../src/persistence/migration/MigrationChain.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,IAAI,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,IAAI,GAAG,OAAO,EAAE,EAAE,GAAG,OAAO;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc,CAAC,OAAO;IAK/B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,eAAe;IALlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAE7D,OAAO;IASP,0FAA0F;IAC1F,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC;IAI1E,wDAAwD;IACxD,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC;IAmB7D;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC;IAwBhE,uCAAuC;IACvC,IAAI,QAAQ,IAAI,MAAM,CAA2B;IAEjD,sDAAsD;IACtD,IAAI,cAAc,IAAI,MAAM,CAAiC;IAE7D,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO;IA8BpC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO;IA8B1D;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa;CAQpE"}

package/dist/persistence/migration/MigrationChain.js

@@ -0,0 +1,159 @@
+import { MigrationError } from './Envelope.js';
+/**
+ * Linear chain of `MigrationStep`s for a single manifest, terminating at
+ * a `currentVersion` known to the running code.  On `upcast(stored)`, the
+ * chain locates the step starting at `stored.version` and applies steps
+ * forward until it reaches `currentVersion`.
+ *
+ * The chain is intentionally narrow: one manifest, one current version,
+ * one linear path.  Multiple types → multiple chains, kept inside an
+ * `EventAdapter.fromJournal` switch by manifest.
+ *
+ *   const chain = MigrationChain.for<DepositedV2>('BankAccount.Deposited', 2)
+ *     .add({ fromVersion: 1, toVersion: 2,
+ *            upcast: (v: DepositedV1): DepositedV2 => ({ ...v, currency: 'USD' }) });
+ *
+ * `chain.upcast({ manifest: 'BankAccount.Deposited', version: 1, payload })`
+ * returns a `DepositedV2`.
+ *
+ * Errors:
+ *   - manifest mismatch → `MigrationError`
+ *   - `stored.version > currentVersion` (downgrade) → `MigrationError`
+ *   - no step available at the current cursor before `currentVersion` is
+ *     reached (chain gap) → `MigrationError` with the gap printed.
+ */
+export class MigrationChain {
+    _manifest;
+    _currentVersion;
+    steps = new Map();
+    downsteps = new Map();
+    constructor(_manifest, _currentVersion) {
+        this._manifest = _manifest;
+        this._currentVersion = _currentVersion;
+        if (!Number.isInteger(_currentVersion) || _currentVersion < 1) {
+            throw new Error(`MigrationChain currentVersion must be a positive integer, got ${_currentVersion}`);
+        }
+    }
+    /** Build an empty chain for `manifest` whose latest known version is `currentVersion`. */
+    static for(manifest, currentVersion) {
+        return new MigrationChain(manifest, currentVersion);
+    }
+    /** Append an upcaster.  Returns `this` for chaining. */
+    add(step) {
+        if (step.fromVersion >= step.toVersion) {
+            throw new Error(`MigrationStep must move forward: fromVersion ${step.fromVersion} >= toVersion ${step.toVersion}`);
+        }
+        if (step.toVersion > this._currentVersion) {
+            throw new Error(`MigrationStep targets v${step.toVersion} but chain currentVersion is ${this._currentVersion}`);
+        }
+        const existing = this.steps.get(step.fromVersion);
+        if (existing) {
+            throw new Error(`MigrationChain already has a step starting at v${step.fromVersion} (→ v${existing.toVersion}); cannot add another`);
+        }
+        this.steps.set(step.fromVersion, step);
+        return this;
+    }
+    /**
+     * Append a downcaster — the inverse of {@link MigrationStep}.
+     * Required when the actor is going to be configured with a
+     * `writeVersion` lower than `currentVersion` (#7).  Steps move
+     * **backward**: `fromVersion > toVersion`.
+     *
+     *   chain.addDown({
+     *     fromVersion: 2, toVersion: 1,
+     *     downcast: (e: DepositedV2): DepositedV1 => {
+     *       const { currency, ...rest } = e; void currency; return rest;
+     *     },
+     *   });
+     */
+    addDown(step) {
+        if (step.fromVersion <= step.toVersion) {
+            throw new Error(`DowncastStep must move backward: fromVersion ${step.fromVersion} <= toVersion ${step.toVersion}`);
+        }
+        if (step.fromVersion > this._currentVersion) {
+            throw new Error(`DowncastStep starts at v${step.fromVersion} but chain currentVersion is ${this._currentVersion}`);
+        }
+        if (step.toVersion < 1) {
+            throw new Error(`DowncastStep targets v${step.toVersion} which is below the v1 floor`);
+        }
+        const existing = this.downsteps.get(step.fromVersion);
+        if (existing) {
+            throw new Error(`MigrationChain already has a downcaster starting at v${step.fromVersion} (→ v${existing.toVersion}); cannot add another`);
+        }
+        this.downsteps.set(step.fromVersion, step);
+        return this;
+    }
+    /** Manifest this chain is bound to. */
+    get manifest() { return this._manifest; }
+    /** Latest version this chain knows how to produce. */
+    get currentVersion() { return this._currentVersion; }
+    /** Apply the chain to a stored frame, returning a current-version value. */
+    upcast(stored) {
+        if (stored.manifest !== this._manifest) {
+            throw new MigrationError(`manifest mismatch: chain is for '${this._manifest}', got '${stored.manifest}'`, stored.manifest, stored.version);
+        }
+        if (stored.version > this._currentVersion) {
+            throw new MigrationError(`cannot downgrade '${stored.manifest}' from v${stored.version} to v${this._currentVersion}`, stored.manifest, stored.version);
+        }
+        let cursor = stored.version;
+        let payload = stored.payload;
+        while (cursor < this._currentVersion) {
+            const step = this.steps.get(cursor);
+            if (!step) {
+                throw new MigrationError(`no upcaster registered for '${stored.manifest}' starting at v${cursor} `
+                    + `(target v${this._currentVersion}); add a MigrationStep with fromVersion=${cursor}`, stored.manifest, stored.version);
+            }
+            payload = step.upcast(payload);
+            cursor = step.toVersion;
+        }
+        return payload;
+    }
+    /**
+     * Convert a current-shape value down to `targetVersion` for a
+     * write-with-old-shape rolling deploy (#7).  Walks the registered
+     * downcasters from `currentVersion` toward `targetVersion`.
+     *
+     * Errors:
+     *   - `targetVersion > currentVersion` → `MigrationError` (we're
+     *     already at or above the target; user should call `toJournalAt`
+     *     with `version: currentVersion`).
+     *   - `targetVersion < 1` → `MigrationError`.
+     *   - chain gap (no downcaster for the current cursor) →
+     *     `MigrationError` with the missing step printed.
+     */
+    downcast(current, targetVersion) {
+        if (!Number.isInteger(targetVersion) || targetVersion < 1) {
+            throw new MigrationError(`targetVersion must be a positive integer, got ${targetVersion}`, this._manifest, this._currentVersion);
+        }
+        if (targetVersion > this._currentVersion) {
+            throw new MigrationError(`cannot downcast '${this._manifest}' from current v${this._currentVersion} to v${targetVersion}: target is newer`, this._manifest, this._currentVersion);
+        }
+        let cursor = this._currentVersion;
+        let payload = current;
+        while (cursor > targetVersion) {
+            const step = this.downsteps.get(cursor);
+            if (!step) {
+                throw new MigrationError(`no downcaster registered for '${this._manifest}' starting at v${cursor} `
+                    + `(target v${targetVersion}); add a DowncastStep with fromVersion=${cursor}`, this._manifest, this._currentVersion);
+            }
+            payload = step.downcast(payload);
+            cursor = step.toVersion;
+        }
+        return payload;
+    }
+    /**
+     * Build an `OutboundFrame` for the write path at `writeVersion`
+     * (defaults to `currentVersion`).  Convenience that combines the
+     * downcast + frame-shape — exactly what `migratingAdapter` calls
+     * from its `toJournal`.
+     */
+    toJournalAt(current, writeVersion) {
+        const v = writeVersion ?? this._currentVersion;
+        return {
+            manifest: this._manifest,
+            version: v,
+            payload: v === this._currentVersion ? current : this.downcast(current, v),
+        };
+    }
+}
+//# sourceMappingURL=MigrationChain.js.map

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

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

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

@@ -0,0 +1,114 @@
+import type { EventAdapter, SnapshotAdapter } from './Adapter.js';
+import type { Codec } from './Codec.js';
+/**
+ * In-process schema registry (#6).  Stores `(manifest, version) →
+ * { codec, upcast? }` triples plus an optional compatibility check
+ * that fires at register time.  Builds an `EventAdapter` /
+ * `SnapshotAdapter` on demand that:
+ *
+ *   - **Writes** at the latest registered version using that
+ *     version's codec — so encode-time validation catches bad
+ *     domain values before they hit the journal.
+ *   - **Reads** by looking up the stored version, decoding with
+ *     that version's codec, then chaining the registered upcasters
+ *     forward to the latest version.
+ *
+ * Confluent-style HTTP schema registries (subject-versioned with
+ * remote compat checks) are out-of-scope for v1.  The interface
+ * below is wide enough that a user can swap in their own
+ * implementation and the rest of the migration machinery continues
+ * to work.
+ *
+ *   const registry = new InMemorySchemaRegistry();
+ *
+ *   registry.register('BankAccount.Deposited', 1, {
+ *     codec: zodCodec(DepositedV1),
+ *   });
+ *
+ *   registry.register('BankAccount.Deposited', 2, {
+ *     codec: zodCodec(DepositedV2),
+ *     upcastFromPrev: (v1: DepositedV1): DepositedV2 => ({ ...v1, currency: 'USD' }),
+ *     compatibility: 'backward',
+ *   });
+ *
+ *   class Account extends PersistentActor<...> {
+ *     eventAdapter() {
+ *       return registry.eventAdapter<DepositedV2>('BankAccount.Deposited');
+ *     }
+ *   }
+ *
+ * **Compatibility modes.**
+ *
+ *   - `'none'` (default) — no check.  Use when you've already
+ *     verified compat externally or for v1 of a manifest where
+ *     there's no previous version yet.
+ *   - `'backward'` — at register time, verify the registry holds an
+ *     `upcastFromPrev` from the version you just registered's
+ *     immediate predecessor.  This is the structural minimum that
+ *     guarantees the read path still works for old data.
+ *   - `'sample'` — same as `'backward'` plus a round-trip on a
+ *     user-supplied sample value: the sample is decoded by the
+ *     previous codec, upcast, and re-encoded by the new codec; if
+ *     the round-trip throws, the registration is rejected.  Catches
+ *     latent upcaster bugs at register time rather than at
+ *     deployment time.
+ */
+/** What a single registered version contributes to the registry. */
+export interface SchemaRegistration<Wire = unknown, Upcasted = unknown> {
+    /** Codec used to validate / shape payloads at this version. */
+    readonly codec: Codec<Wire>;
+    /**
+     * Pure function `prevVersionDomain → thisVersionDomain` used on
+     * the read path to bring data forward.  Required for any version
+     * > 1 if reads from older data are expected to succeed.
+     */
+    readonly upcastFromPrev?: (prev: unknown) => Upcasted;
+    /** Compatibility-check mode applied at register time.  Default `'none'`. */
+    readonly compatibility?: 'none' | 'backward' | 'sample';
+    /**
+     * Optional sample value used by `'sample'` compat checks — passed
+     * through the previous version's encode → decode → upcast → this
+     * version's encode round-trip.  Throws if any step fails.
+     */
+    readonly sample?: unknown;
+}
+export interface SchemaDescriptor extends SchemaRegistration {
+    readonly manifest: string;
+    readonly version: number;
+}
+/** Public API of any schema registry impl. */
+export interface SchemaRegistry {
+    /**
+     * Add or replace the registration for `(manifest, version)`.
+     * Runs the configured compat check; throws on incompatibility.
+     * Re-registering the same `(manifest, version)` overwrites — the
+     * registry doesn't enforce immutability, that's an operator
+     * concern.
+     */
+    register<Wire = unknown, Upcasted = unknown>(manifest: string, version: number, registration: SchemaRegistration<Wire, Upcasted>): void;
+    /** Look up the registration for `(manifest, version)`, if any. */
+    get(manifest: string, version: number): SchemaDescriptor | undefined;
+    /** Highest registered version for `manifest`, or `undefined` if unknown. */
+    latestVersion(manifest: string): number | undefined;
+    /** Snapshot of every registration — primarily for debugging / introspection. */
+    list(): ReadonlyArray<SchemaDescriptor>;
+    /**
+     * Build an `EventAdapter` that writes at the latest registered
+     * version of `manifest` and reads any registered version by
+     * chaining upcasters forward.
+     */
+    eventAdapter<E>(manifest: string): EventAdapter<E, unknown>;
+    /** Same as `eventAdapter` but typed for snapshot/state actors. */
+    snapshotAdapter<S>(manifest: string): SnapshotAdapter<S, unknown>;
+}
+/** In-memory `SchemaRegistry` impl.  All state lives in one process. */
+export declare class InMemorySchemaRegistry implements SchemaRegistry {
+    private readonly entries;
+    register<Wire = unknown, Upcasted = unknown>(manifest: string, version: number, registration: SchemaRegistration<Wire, Upcasted>): void;
+    get(manifest: string, version: number): SchemaDescriptor | undefined;
+    latestVersion(manifest: string): number | undefined;
+    list(): ReadonlyArray<SchemaDescriptor>;
+    eventAdapter<E>(manifest: string): EventAdapter<E, unknown>;
+    snapshotAdapter<S>(manifest: string): SnapshotAdapter<S, unknown>;
+}
+//# sourceMappingURL=SchemaRegistry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaRegistry.d.ts","sourceRoot":"","sources":["../../../src/persistence/migration/SchemaRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAiB,eAAe,EAAe,MAAM,cAAc,CAAC;AAC9F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,oEAAoE;AACpE,MAAM,WAAW,kBAAkB,CAAC,IAAI,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACpE,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,QAAQ,CAAC;IACtD,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;IACxD;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,EACzC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EACjC,YAAY,EAAE,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,GAC/C,IAAI,CAAC;IAER,kEAAkE;IAClE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAErE,4EAA4E;IAC5E,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEpD,gFAAgF;IAChF,IAAI,IAAI,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAExC;;;;OAIG;IACH,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAE5D,kEAAkE;IAClE,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;CACnE;AAID,wEAAwE;AACxE,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoD;IAE5E,QAAQ,CAAC,IAAI,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,EACzC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EACjC,YAAY,EAAE,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,GAC/C,IAAI;IAoDP,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIpE,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQnD,IAAI,IAAI,aAAa,CAAC,gBAAgB,CAAC;IAQvC,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC;IA+C3D,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC;CAIlE"}

package/dist/persistence/migration/SchemaRegistry.js

@@ -0,0 +1,112 @@
+import { MigrationError } from './Envelope.js';
+/* ============================== impl ================================== */
+/** In-memory `SchemaRegistry` impl.  All state lives in one process. */
+export class InMemorySchemaRegistry {
+    entries = new Map();
+    register(manifest, version, registration) {
+        if (!Number.isInteger(version) || version < 1) {
+            throw new Error(`SchemaRegistry.register: version must be a positive integer, got ${version}`);
+        }
+        const compat = registration.compatibility ?? 'none';
+        if (compat !== 'none') {
+            const prev = this.get(manifest, version - 1);
+            if (!prev) {
+                throw new Error(`SchemaRegistry.register: compatibility '${compat}' requested for ${manifest}@v${version}, `
+                    + `but v${version - 1} is not registered`);
+            }
+            if (!registration.upcastFromPrev) {
+                throw new Error(`SchemaRegistry.register: ${manifest}@v${version} compatibility=${compat} requires upcastFromPrev`);
+            }
+            if (compat === 'sample') {
+                if (registration.sample === undefined) {
+                    throw new Error(`SchemaRegistry.register: ${manifest}@v${version} compatibility='sample' requires a sample value`);
+                }
+                try {
+                    const wirePrev = prev.codec.encode(registration.sample);
+                    const decodedPrev = prev.codec.decode(wirePrev);
+                    const upcasted = registration.upcastFromPrev(decodedPrev);
+                    // Re-encode through the new codec — if the upcasted value
+                    // doesn't match the new schema, the register fails loud.
+                    registration.codec.encode(upcasted);
+                }
+                catch (err) {
+                    throw new Error(`SchemaRegistry.register: ${manifest}@v${version} sample-compat check failed: `
+                        + (err instanceof Error ? err.message : String(err)));
+                }
+            }
+        }
+        const descriptor = {
+            manifest, version,
+            codec: registration.codec,
+            upcastFromPrev: registration.upcastFromPrev,
+            compatibility: compat,
+            sample: registration.sample,
+        };
+        let bucket = this.entries.get(manifest);
+        if (!bucket) {
+            bucket = new Map();
+            this.entries.set(manifest, bucket);
+        }
+        bucket.set(version, descriptor);
+    }
+    get(manifest, version) {
+        return this.entries.get(manifest)?.get(version);
+    }
+    latestVersion(manifest) {
+        const bucket = this.entries.get(manifest);
+        if (!bucket || bucket.size === 0)
+            return undefined;
+        let latest = -Infinity;
+        for (const v of bucket.keys())
+            if (v > latest)
+                latest = v;
+        return latest === -Infinity ? undefined : latest;
+    }
+    list() {
+        const out = [];
+        for (const bucket of this.entries.values()) {
+            for (const d of bucket.values())
+                out.push(d);
+        }
+        return out;
+    }
+    eventAdapter(manifest) {
+        const adapter = {
+            manifest: () => manifest,
+            toJournal: (event) => {
+                const latest = this.latestVersion(manifest);
+                if (latest === undefined) {
+                    throw new MigrationError(`SchemaRegistry: no schema registered for '${manifest}' on the write path`, manifest);
+                }
+                const desc = this.get(manifest, latest);
+                const validated = desc.codec.encode(event);
+                return { manifest, version: latest, payload: validated };
+            },
+            fromJournal: (stored) => {
+                const startDesc = this.get(stored.manifest, stored.version);
+                if (!startDesc) {
+                    throw new MigrationError(`SchemaRegistry: no schema registered for '${stored.manifest}'@v${stored.version} on the read path`, stored.manifest, stored.version);
+                }
+                let value = startDesc.codec.decode(stored.payload);
+                const latest = this.latestVersion(stored.manifest);
+                for (let v = stored.version + 1; v <= latest; v++) {
+                    const desc = this.get(stored.manifest, v);
+                    if (!desc) {
+                        throw new MigrationError(`SchemaRegistry: gap on the upcast path for '${stored.manifest}': v${v} not registered`, stored.manifest, stored.version);
+                    }
+                    if (!desc.upcastFromPrev) {
+                        throw new MigrationError(`SchemaRegistry: ${stored.manifest}@v${v} has no upcastFromPrev — cannot bring v${stored.version} forward`, stored.manifest, stored.version);
+                    }
+                    value = desc.upcastFromPrev(value);
+                }
+                return value;
+            },
+        };
+        return adapter;
+    }
+    snapshotAdapter(manifest) {
+        // Same shape as eventAdapter — keep one implementation, two types.
+        return this.eventAdapter(manifest);
+    }
+}
+//# sourceMappingURL=SchemaRegistry.js.map

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

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

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

@@ -0,0 +1,56 @@
+import type { EventAdapter, SnapshotAdapter } from './Adapter.js';
+/**
+ * Spec for `defaultsAdapter` / `defaultsSnapshotAdapter`.
+ *
+ *   manifest        — stable type identity, e.g. 'BankAccount.Deposited'
+ *   currentVersion  — version emitted by *this* code revision
+ *   defaults[fromV] — fields to merge in when reading a payload at
+ *                     version fromV that is then carried forward to
+ *                     version fromV+1 by simple object spread
+ *   writeVersion    — version to emit on `toJournal` (#7).  Defaults to
+ *                     `currentVersion`.  When set lower than current,
+ *                     fields added at versions in `[writeVersion+1,
+ *                     currentVersion]` are stripped on write — the
+ *                     mechanical inverse of the additive `defaults`
+ *                     merge.  Used during rolling deploys: v2 nodes
+ *                     keep emitting v1 events while v1 readers still
+ *                     exist; flip `writeVersion` to v2 once every
+ *                     reader has been upgraded.
+ *
+ * The merge is `{ ...defaults[fromV], ...payload }` — the stored payload
+ * always wins, so existing fields are never overwritten by defaults.
+ * Run repeatedly for every step on the path stored→currentVersion.
+ */
+export interface DefaultsAdapterSpec<E> {
+    readonly manifest: string;
+    readonly currentVersion: number;
+    readonly defaults: {
+        readonly [fromVersion: number]: Partial<E>;
+    };
+    readonly writeVersion?: number;
+}
+/**
+ * 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 declare function defaultsAdapter<E extends object>(spec: DefaultsAdapterSpec<E>): EventAdapter<E, E>;
+/**
+ * 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 declare function defaultsSnapshotAdapter<S extends object>(spec: DefaultsAdapterSpec<S>): SnapshotAdapter<S, S>;
+//# sourceMappingURL=defaultsAdapter.d.ts.map