actor-ts 0.9.0

package/dist/Supervision.d.ts

@@ -0,0 +1,66 @@
+/** Supervisor directives decide what happens to a failing child actor. */
+export declare enum Directive {
+    /** Ignore the failure and keep the actor state; resume message processing. */
+    Resume = "resume",
+    /** Destroy and recreate the actor, losing its state. */
+    Restart = "restart",
+    /** Stop the failing actor permanently. */
+    Stop = "stop",
+    /** Escalate the failure to the supervisor's own supervisor. */
+    Escalate = "escalate"
+}
+export type Decider = (error: Error) => Directive;
+/** Descriptor for a supervision strategy. */
+export interface SupervisorStrategy {
+    readonly scope: 'one-for-one' | 'all-for-one';
+    readonly decider: Decider;
+    /** Maximum number of restarts tolerated within the time window. -1 = unlimited. */
+    readonly maxRetries: number;
+    /** Sliding time window in ms. 0 = no window (counts are never reset). */
+    readonly withinTimeRangeMs: number;
+}
+export interface StrategyOptions {
+    maxRetries?: number;
+    withinTimeRangeMs?: number;
+}
+/** Applies the directive only to the failing child. */
+export declare class OneForOneStrategy implements SupervisorStrategy {
+    readonly decider: Decider;
+    readonly scope: "one-for-one";
+    readonly maxRetries: number;
+    readonly withinTimeRangeMs: number;
+    constructor(decider: Decider, opts?: StrategyOptions);
+}
+/** Applies the directive to every child when any one fails. */
+export declare class AllForOneStrategy implements SupervisorStrategy {
+    readonly decider: Decider;
+    readonly scope: "all-for-one";
+    readonly maxRetries: number;
+    readonly withinTimeRangeMs: number;
+    constructor(decider: Decider, opts?: StrategyOptions);
+}
+/** Default: restart failing child, up to 10 times per minute. */
+export declare const defaultStrategy: SupervisorStrategy;
+/** Always stop failing children. Useful for "let it crash" setups where a parent replaces children lazily. */
+export declare const stoppingStrategy: SupervisorStrategy;
+/** Always escalate. */
+export declare const escalatingStrategy: SupervisorStrategy;
+/**
+ * Build a decider from a list of {errorType, directive} mappings, falling back
+ * to a configurable default.
+ */
+export declare function decideBy(cases: Array<{
+    match: new (...args: any[]) => Error;
+    then: Directive;
+}>, fallback?: Directive): Decider;
+/** Raised when preStart / actor construction fails. */
+export declare class ActorInitializationError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Raised when an actor explicitly watches another that terminates and does not handle Terminated. */
+export declare class DeathPactError extends Error {
+    readonly actorPath: string;
+    constructor(actorPath: string);
+}
+//# sourceMappingURL=Supervision.d.ts.map

package/dist/Supervision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Supervision.d.ts","sourceRoot":"","sources":["../src/Supervision.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,oBAAY,SAAS;IACnB,8EAA8E;IAC9E,MAAM,WAAW;IACjB,wDAAwD;IACxD,OAAO,YAAY;IACnB,0CAA0C;IAC1C,IAAI,SAAS;IACb,+DAA+D;IAC/D,QAAQ,aAAa;CACtB;AAED,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC;AAElD,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,uDAAuD;AACvD,qBAAa,iBAAkB,YAAW,kBAAkB;aAI9B,OAAO,EAAE,OAAO;IAH5C,QAAQ,CAAC,KAAK,EAAG,aAAa,CAAU;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBACP,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,eAAoB;CAIzE;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,YAAW,kBAAkB;aAI9B,OAAO,EAAE,OAAO;IAH5C,QAAQ,CAAC,KAAK,EAAG,aAAa,CAAU;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;gBACP,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,eAAoB;CAIzE;AAED,iEAAiE;AACjE,eAAO,MAAM,eAAe,EAAE,kBAG7B,CAAC;AAEF,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,EAAE,kBAE9B,CAAC;AAEF,uBAAuB;AACvB,eAAO,MAAM,kBAAkB,EAAE,kBAEhC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,KAAK,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,EACvE,QAAQ,GAAE,SAA6B,GACtC,OAAO,CAOT;AAID,uDAAuD;AACvD,qBAAa,wBAAyB,SAAQ,KAAK;aACJ,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI7D;AAED,sGAAsG;AACtG,qBAAa,cAAe,SAAQ,KAAK;aACX,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAI9C"}

package/dist/Supervision.js

@@ -0,0 +1,75 @@
+/** Supervisor directives decide what happens to a failing child actor. */
+export var Directive;
+(function (Directive) {
+    /** Ignore the failure and keep the actor state; resume message processing. */
+    Directive["Resume"] = "resume";
+    /** Destroy and recreate the actor, losing its state. */
+    Directive["Restart"] = "restart";
+    /** Stop the failing actor permanently. */
+    Directive["Stop"] = "stop";
+    /** Escalate the failure to the supervisor's own supervisor. */
+    Directive["Escalate"] = "escalate";
+})(Directive || (Directive = {}));
+/** Applies the directive only to the failing child. */
+export class OneForOneStrategy {
+    decider;
+    scope = 'one-for-one';
+    maxRetries;
+    withinTimeRangeMs;
+    constructor(decider, opts = {}) {
+        this.decider = decider;
+        this.maxRetries = opts.maxRetries ?? -1;
+        this.withinTimeRangeMs = opts.withinTimeRangeMs ?? 0;
+    }
+}
+/** Applies the directive to every child when any one fails. */
+export class AllForOneStrategy {
+    decider;
+    scope = 'all-for-one';
+    maxRetries;
+    withinTimeRangeMs;
+    constructor(decider, opts = {}) {
+        this.decider = decider;
+        this.maxRetries = opts.maxRetries ?? -1;
+        this.withinTimeRangeMs = opts.withinTimeRangeMs ?? 0;
+    }
+}
+/** Default: restart failing child, up to 10 times per minute. */
+export const defaultStrategy = new OneForOneStrategy(() => Directive.Restart, { maxRetries: 10, withinTimeRangeMs: 60_000 });
+/** Always stop failing children. Useful for "let it crash" setups where a parent replaces children lazily. */
+export const stoppingStrategy = new OneForOneStrategy(() => Directive.Stop);
+/** Always escalate. */
+export const escalatingStrategy = new OneForOneStrategy(() => Directive.Escalate);
+/**
+ * Build a decider from a list of {errorType, directive} mappings, falling back
+ * to a configurable default.
+ */
+export function decideBy(cases, fallback = Directive.Restart) {
+    return (err) => {
+        for (const c of cases) {
+            if (err instanceof c.match)
+                return c.then;
+        }
+        return fallback;
+    };
+}
+/* -------------------------- Standard error types -------------------------- */
+/** Raised when preStart / actor construction fails. */
+export class ActorInitializationError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'ActorInitializationError';
+    }
+}
+/** Raised when an actor explicitly watches another that terminates and does not handle Terminated. */
+export class DeathPactError extends Error {
+    actorPath;
+    constructor(actorPath) {
+        super(`Death pact with terminated actor ${actorPath}`);
+        this.actorPath = actorPath;
+        this.name = 'DeathPactError';
+    }
+}
+//# sourceMappingURL=Supervision.js.map

package/dist/Supervision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Supervision.js","sourceRoot":"","sources":["../src/Supervision.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,CAAN,IAAY,SASX;AATD,WAAY,SAAS;IACnB,8EAA8E;IAC9E,8BAAiB,CAAA;IACjB,wDAAwD;IACxD,gCAAmB,CAAA;IACnB,0CAA0C;IAC1C,0BAAa,CAAA;IACb,+DAA+D;IAC/D,kCAAqB,CAAA;AACvB,CAAC,EATW,SAAS,KAAT,SAAS,QASpB;AAmBD,uDAAuD;AACvD,MAAM,OAAO,iBAAiB;IAIA;IAHnB,KAAK,GAAG,aAAsB,CAAC;IAC/B,UAAU,CAAS;IACnB,iBAAiB,CAAS;IACnC,YAA4B,OAAgB,EAAE,OAAwB,EAAE;QAA5C,YAAO,GAAP,OAAO,CAAS;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,CAAC,CAAC;IACvD,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,iBAAiB;IAIA;IAHnB,KAAK,GAAG,aAAsB,CAAC;IAC/B,UAAU,CAAS;IACnB,iBAAiB,CAAS;IACnC,YAA4B,OAAgB,EAAE,OAAwB,EAAE;QAA5C,YAAO,GAAP,OAAO,CAAS;QAC1C,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,IAAI,CAAC,CAAC;IACvD,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAuB,IAAI,iBAAiB,CACtE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EACvB,EAAE,UAAU,EAAE,EAAE,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAC9C,CAAC;AAEF,8GAA8G;AAC9G,MAAM,CAAC,MAAM,gBAAgB,GAAuB,IAAI,iBAAiB,CACvE,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CACrB,CAAC;AAEF,uBAAuB;AACvB,MAAM,CAAC,MAAM,kBAAkB,GAAuB,IAAI,iBAAiB,CACzE,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,CACzB,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAuE,EACvE,WAAsB,SAAS,CAAC,OAAO;IAEvC,OAAO,CAAC,GAAU,EAAa,EAAE;QAC/B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,GAAG,YAAY,CAAC,CAAC,KAAK;gBAAE,OAAO,CAAC,CAAC,IAAI,CAAC;QAC5C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;AACJ,CAAC;AAED,gFAAgF;AAEhF,uDAAuD;AACvD,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACJ;IAA7C,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,sGAAsG;AACtG,MAAM,OAAO,cAAe,SAAQ,KAAK;IACX;IAA5B,YAA4B,SAAiB;QAC3C,KAAK,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;QAD7B,cAAS,GAAT,SAAS,CAAQ;QAE3C,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/dist/SystemMessages.d.ts

@@ -0,0 +1,56 @@
+import type { ActorRef } from './ActorRef.js';
+/**
+ * Gracefully stops an actor after it has processed all currently
+ * enqueued messages.  Classic actor-model "stop after drain" semantic.
+ */
+export declare class PoisonPill {
+    static readonly instance: PoisonPill;
+    private constructor();
+    toString(): string;
+}
+/**
+ * Immediately terminates the actor (raises an ActorKilledException inside the cell).
+ */
+export declare class Kill {
+    static readonly instance: Kill;
+    private constructor();
+    toString(): string;
+}
+/**
+ * Delivered to watchers when a watched actor has been terminated.
+ */
+export declare class Terminated {
+    readonly actor: ActorRef;
+    readonly existenceConfirmed: boolean;
+    readonly addressTerminated: boolean;
+    constructor(actor: ActorRef, existenceConfirmed?: boolean, addressTerminated?: boolean);
+    toString(): string;
+}
+/**
+ * Sent to an actor when it has not received a message within its configured
+ * receive timeout. See ActorContext.setReceiveTimeout.
+ */
+export declare class ReceiveTimeout {
+    static readonly instance: ReceiveTimeout;
+    private constructor();
+    toString(): string;
+}
+/**
+ * Wraps an undeliverable message sent to dead letters.
+ */
+export declare class DeadLetter {
+    readonly message: unknown;
+    readonly sender: ActorRef | null;
+    readonly recipient: ActorRef;
+    constructor(message: unknown, sender: ActorRef | null, recipient: ActorRef);
+    toString(): string;
+}
+/** Thrown when an actor handles a Kill system message. */
+export declare class ActorKilledError extends Error {
+    constructor();
+}
+/** Thrown inside askers when the ask target times out. */
+export declare class AskTimeoutError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=SystemMessages.d.ts.map

package/dist/SystemMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemMessages.d.ts","sourceRoot":"","sources":["../src/SystemMessages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;GAGG;AACH,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,QAAQ,aAAoB;IAC5C,OAAO;IACP,QAAQ,IAAI,MAAM;CACnB;AAED;;GAEG;AACH,qBAAa,IAAI;IACf,MAAM,CAAC,QAAQ,CAAC,QAAQ,OAAc;IACtC,OAAO;IACP,QAAQ,IAAI,MAAM;CACnB;AAED;;GAEG;AACH,qBAAa,UAAU;aAEH,KAAK,EAAE,QAAQ;aACf,kBAAkB,EAAE,OAAO;aAC3B,iBAAiB,EAAE,OAAO;gBAF1B,KAAK,EAAE,QAAQ,EACf,kBAAkB,GAAE,OAAc,EAClC,iBAAiB,GAAE,OAAe;IAEpD,QAAQ,IAAI,MAAM;CACnB;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,MAAM,CAAC,QAAQ,CAAC,QAAQ,iBAAwB;IAChD,OAAO;IACP,QAAQ,IAAI,MAAM;CACnB;AAED;;GAEG;AACH,qBAAa,UAAU;aAEH,OAAO,EAAE,OAAO;aAChB,MAAM,EAAE,QAAQ,GAAG,IAAI;aACvB,SAAS,EAAE,QAAQ;gBAFnB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,QAAQ,GAAG,IAAI,EACvB,SAAS,EAAE,QAAQ;IAErC,QAAQ,IAAI,MAAM;CAGnB;AAED,0DAA0D;AAC1D,qBAAa,gBAAiB,SAAQ,KAAK;;CAK1C;AAED,0DAA0D;AAC1D,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B"}

package/dist/SystemMessages.js

@@ -0,0 +1,71 @@
+/**
+ * Gracefully stops an actor after it has processed all currently
+ * enqueued messages.  Classic actor-model "stop after drain" semantic.
+ */
+export class PoisonPill {
+    static instance = new PoisonPill();
+    constructor() { }
+    toString() { return 'PoisonPill'; }
+}
+/**
+ * Immediately terminates the actor (raises an ActorKilledException inside the cell).
+ */
+export class Kill {
+    static instance = new Kill();
+    constructor() { }
+    toString() { return 'Kill'; }
+}
+/**
+ * Delivered to watchers when a watched actor has been terminated.
+ */
+export class Terminated {
+    actor;
+    existenceConfirmed;
+    addressTerminated;
+    constructor(actor, existenceConfirmed = true, addressTerminated = false) {
+        this.actor = actor;
+        this.existenceConfirmed = existenceConfirmed;
+        this.addressTerminated = addressTerminated;
+    }
+    toString() { return `Terminated(${this.actor})`; }
+}
+/**
+ * Sent to an actor when it has not received a message within its configured
+ * receive timeout. See ActorContext.setReceiveTimeout.
+ */
+export class ReceiveTimeout {
+    static instance = new ReceiveTimeout();
+    constructor() { }
+    toString() { return 'ReceiveTimeout'; }
+}
+/**
+ * Wraps an undeliverable message sent to dead letters.
+ */
+export class DeadLetter {
+    message;
+    sender;
+    recipient;
+    constructor(message, sender, recipient) {
+        this.message = message;
+        this.sender = sender;
+        this.recipient = recipient;
+    }
+    toString() {
+        return `DeadLetter(msg=${String(this.message)}, from=${this.sender ?? 'none'}, to=${this.recipient})`;
+    }
+}
+/** Thrown when an actor handles a Kill system message. */
+export class ActorKilledError extends Error {
+    constructor() {
+        super('Kill');
+        this.name = 'ActorKilledError';
+    }
+}
+/** Thrown inside askers when the ask target times out. */
+export class AskTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AskTimeoutError';
+    }
+}
+//# sourceMappingURL=SystemMessages.js.map

package/dist/SystemMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemMessages.js","sourceRoot":"","sources":["../src/SystemMessages.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,UAAU;IACrB,MAAM,CAAU,QAAQ,GAAG,IAAI,UAAU,EAAE,CAAC;IAC5C,gBAAuB,CAAC;IACxB,QAAQ,KAAa,OAAO,YAAY,CAAC,CAAC,CAAC;;AAG7C;;GAEG;AACH,MAAM,OAAO,IAAI;IACf,MAAM,CAAU,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;IACtC,gBAAuB,CAAC;IACxB,QAAQ,KAAa,OAAO,MAAM,CAAC,CAAC,CAAC;;AAGvC;;GAEG;AACH,MAAM,OAAO,UAAU;IAEH;IACA;IACA;IAHlB,YACkB,KAAe,EACf,qBAA8B,IAAI,EAClC,oBAA6B,KAAK;QAFlC,UAAK,GAAL,KAAK,CAAU;QACf,uBAAkB,GAAlB,kBAAkB,CAAgB;QAClC,sBAAiB,GAAjB,iBAAiB,CAAiB;IACjD,CAAC;IACJ,QAAQ,KAAa,OAAO,cAAc,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;CAC3D;AAED;;;GAGG;AACH,MAAM,OAAO,cAAc;IACzB,MAAM,CAAU,QAAQ,GAAG,IAAI,cAAc,EAAE,CAAC;IAChD,gBAAuB,CAAC;IACxB,QAAQ,KAAa,OAAO,gBAAgB,CAAC,CAAC,CAAC;;AAGjD;;GAEG;AACH,MAAM,OAAO,UAAU;IAEH;IACA;IACA;IAHlB,YACkB,OAAgB,EAChB,MAAuB,EACvB,SAAmB;QAFnB,YAAO,GAAP,OAAO,CAAS;QAChB,WAAM,GAAN,MAAM,CAAiB;QACvB,cAAS,GAAT,SAAS,CAAU;IAClC,CAAC;IACJ,QAAQ;QACN,OAAO,kBAAkB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,MAAM,IAAI,MAAM,QAAQ,IAAI,CAAC,SAAS,GAAG,CAAC;IACxG,CAAC;CACF;AAED,0DAA0D;AAC1D,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC;QACE,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,0DAA0D;AAC1D,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/cache/Cache.d.ts

@@ -0,0 +1,75 @@
+import type { Option } from '../util/Option.js';
+/**
+ * Generic distributed-cache abstraction — used by HTTP middleware
+ * (response-cache, rate-limit, idempotency-key) and the optional
+ * `CachedSnapshotStore` decorator.  Three implementations ship:
+ *
+ *   - `InMemoryCache`  — single-process Map; default, ideal for tests/dev.
+ *   - `RedisCache`     — wraps `ioredis` (optional peer dependency).
+ *   - `MemcachedCache` — wraps `memjs` (optional peer dependency).
+ *
+ * The surface is intentionally small.  Seven operations cover ~95% of the
+ * real cases in this codebase; we deliberately exclude pattern-scans
+ * (anti-pattern at scale) and pub/sub (already provided by the cluster
+ * layer).  Bulk `mget` / `mset` (#14) cut round-trips for the hot
+ * sharded-entity-hydration path after a rebalance.
+ *
+ * **Failure model:** a cache is opportunistic by definition.  Backends
+ * are encouraged to *return* a sensible default rather than throw on
+ * transient connection errors — `get` returning None on network failure
+ * is fine, since the caller's job is to fall back to the source of
+ * truth anyway.  Exceptions are reserved for misuse (invalid TTL, etc).
+ */
+export interface Cache {
+    /** Get a value; returns None on miss, expiry, or transient backend failure. */
+    get<V = unknown>(key: string): Promise<Option<V>>;
+    /** Set a value with optional TTL (milliseconds).  Omitting `ttlMs` means no expiry. */
+    set<V = unknown>(key: string, value: V, ttlMs?: number): Promise<void>;
+    /**
+     * Atomic increment by 1 — returns the **new** value.  When `ttlMs` is
+     * supplied AND the key was newly created (counter value is 1 after
+     * the call), the TTL is set; subsequent increments do not refresh it.
+     * This is the right semantics for a fixed-window rate-limiter.
+     */
+    incr(key: string, ttlMs?: number): Promise<number>;
+    /**
+     * Set only if the key does not yet exist.  Returns true on success
+     * (the value was stored), false on collision (someone else got there
+     * first).  Used as the kernel of idempotency-key dedup.
+     */
+    setIfAbsent<V = unknown>(key: string, value: V, ttlMs?: number): Promise<boolean>;
+    /** Delete one or many keys.  Idempotent — missing keys are a no-op. */
+    delete(...keys: string[]): Promise<void>;
+    /**
+     * Bulk get (#14) — fetch multiple keys in a single round-trip when
+     * the backend supports it.  Returns a `Map` keyed by the input
+     * keys; misses (no entry, expired, malformed payload, transient
+     * backend failure) are simply absent from the result rather than
+     * mapped to `undefined`.  `Map.get(k)` therefore returns `V |
+     * undefined` with the same "missing key" semantics as the
+     * single-key `get`.
+     *
+     * Order of the returned Map matches the order of the input keys
+     * for backends that support it (Redis MGET); backends that fall
+     * back to parallel single-key reads (Memcached) may surface a
+     * different iteration order — don't rely on it.
+     */
+    mget<V = unknown>(keys: ReadonlyArray<string>): Promise<Map<string, V>>;
+    /**
+     * Bulk set (#14) — write multiple key/value pairs with a shared
+     * TTL.  The atomicity guarantee is per backend: Redis emits a
+     * single `MSET` (no-TTL) or pipelined `SET ... PX` (with-TTL);
+     * Memcached has no native bulk write so the calls go out in
+     * parallel.  Single-process backends (InMemory) trivially see
+     * the whole bag at once.  `ttlMs` applies to every entry.
+     */
+    mset<V = unknown>(entries: ReadonlyMap<string, V>, ttlMs?: number): Promise<void>;
+    /** Best-effort teardown.  Idempotent. */
+    close?(): Promise<void>;
+}
+/** Generic cache failure — backends may extend this. */
+export declare class CacheError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+//# sourceMappingURL=Cache.d.ts.map

package/dist/cache/Cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.d.ts","sourceRoot":"","sources":["../../src/cache/Cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,KAAK;IACpB,+EAA+E;IAC/E,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAElD,uFAAuF;IACvF,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvE;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnD;;;;OAIG;IACH,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAElF,uEAAuE;IACvE,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IAExE;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElF,yCAAyC;IACzC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,wDAAwD;AACxD,qBAAa,UAAW,SAAQ,KAAK;aACU,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI7D"}

package/dist/cache/Cache.js

@@ -0,0 +1,10 @@
+/** Generic cache failure — backends may extend this. */
+export class CacheError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'CacheError';
+    }
+}
+//# sourceMappingURL=Cache.js.map

package/dist/cache/Cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cache.js","sourceRoot":"","sources":["../../src/cache/Cache.ts"],"names":[],"mappings":"AA8EA,wDAAwD;AACxD,MAAM,OAAO,UAAW,SAAQ,KAAK;IACU;IAA7C,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF"}

package/dist/cache/CacheExtension.d.ts

@@ -0,0 +1,44 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import { type Extension, type ExtensionId } from '../Extension.js';
+import type { Cache } from './Cache.js';
+/**
+ * System-wide registry for named caches.  Apps that need more than one
+ * cache (e.g. a Redis-backed response cache and a separate Memcached
+ * idempotency-store) register each one under a stable name and look it
+ * up via `system.extension(CacheExtensionId).cache(name)`.
+ *
+ * The `default` cache is always available and starts as an
+ * `InMemoryCache` — handy for tests and dev.  Registering a different
+ * factory under `'default'` (or selecting via the HOCON path
+ * `actor-ts.cache.default.plugin`) replaces it.
+ */
+export declare class CacheExtension implements Extension {
+    private readonly system;
+    private readonly factories;
+    private readonly instances;
+    constructor(system: ActorSystem);
+    /**
+     * Register a cache factory under `pluginId`.  The factory runs lazily
+     * on the first `cache(name)` call that resolves to this plugin via
+     * config.  Re-registering the same id replaces the factory and forces
+     * a re-instantiation on next access.
+     */
+    registerCache(pluginId: string, factory: (system: ActorSystem) => Cache): void;
+    /**
+     * Resolve a cache by name.  Names map to plugin ids via the HOCON
+     * path `actor-ts.cache.<name>.plugin`.  Unknown names fall back to
+     * the in-memory plugin so callers always get *something* — handy for
+     * tests where config wiring would be busywork.
+     */
+    cache(name?: string): Cache;
+    /** Replace the cache instance for `name` directly — useful for tests. */
+    setCache(name: string, cache: Cache): void;
+    /** Best-effort close of every instantiated cache. */
+    close(): Promise<void>;
+    private pluginIdFor;
+}
+export declare const CacheExtensionId: ExtensionId<CacheExtension>;
+export declare const REDIS_CACHE_PLUGIN_ID: "actor-ts.cache.redis";
+export declare const MEMCACHED_CACHE_PLUGIN_ID: "actor-ts.cache.memcached";
+export declare const IN_MEMORY_CACHE_PLUGIN_ID: "actor-ts.cache.in-memory";
+//# sourceMappingURL=CacheExtension.d.ts.map

package/dist/cache/CacheExtension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheExtension.d.ts","sourceRoot":"","sources":["../../src/cache/CacheExtension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,YAAW,SAAS;IAIlC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqD;IAC/E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;gBAEzB,MAAM,EAAE,WAAW;IAIhD;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,KAAK,GAAG,IAAI;IAQ9E;;;;;OAKG;IACH,KAAK,CAAC,IAAI,GAAE,MAAkB,GAAG,KAAK;IAWtC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAI1C,qDAAqD;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B,OAAO,CAAC,WAAW;CAMpB;AAED,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,cAAc,CAGxD,CAAC;AAIF,eAAO,MAAM,qBAAqB,wBAAyB,CAAC;AAC5D,eAAO,MAAM,yBAAyB,4BAA6B,CAAC;AACpE,eAAO,MAAM,yBAAyB,4BAA4B,CAAC"}

package/dist/cache/CacheExtension.js

@@ -0,0 +1,77 @@
+import { ConfigKeys } from '../config/ConfigKeys.js';
+import { extensionId } from '../Extension.js';
+import { InMemoryCache } from './InMemoryCache.js';
+/**
+ * System-wide registry for named caches.  Apps that need more than one
+ * cache (e.g. a Redis-backed response cache and a separate Memcached
+ * idempotency-store) register each one under a stable name and look it
+ * up via `system.extension(CacheExtensionId).cache(name)`.
+ *
+ * The `default` cache is always available and starts as an
+ * `InMemoryCache` — handy for tests and dev.  Registering a different
+ * factory under `'default'` (or selecting via the HOCON path
+ * `actor-ts.cache.default.plugin`) replaces it.
+ */
+export class CacheExtension {
+    system;
+    factories = new Map();
+    instances = new Map();
+    constructor(system) {
+        this.system = system;
+        this.factories.set(ConfigKeys.cache.inMemory, () => new InMemoryCache());
+    }
+    /**
+     * Register a cache factory under `pluginId`.  The factory runs lazily
+     * on the first `cache(name)` call that resolves to this plugin via
+     * config.  Re-registering the same id replaces the factory and forces
+     * a re-instantiation on next access.
+     */
+    registerCache(pluginId, factory) {
+        this.factories.set(pluginId, factory);
+        // Force re-resolution if any active instance was built from this plugin.
+        for (const [name, _inst] of this.instances) {
+            if (this.pluginIdFor(name) === pluginId)
+                this.instances.delete(name);
+        }
+    }
+    /**
+     * Resolve a cache by name.  Names map to plugin ids via the HOCON
+     * path `actor-ts.cache.<name>.plugin`.  Unknown names fall back to
+     * the in-memory plugin so callers always get *something* — handy for
+     * tests where config wiring would be busywork.
+     */
+    cache(name = 'default') {
+        const existing = this.instances.get(name);
+        if (existing)
+            return existing;
+        const pluginId = this.pluginIdFor(name);
+        const factory = this.factories.get(pluginId)
+            ?? this.factories.get(ConfigKeys.cache.inMemory);
+        const inst = factory(this.system);
+        this.instances.set(name, inst);
+        return inst;
+    }
+    /** Replace the cache instance for `name` directly — useful for tests. */
+    setCache(name, cache) {
+        this.instances.set(name, cache);
+    }
+    /** Best-effort close of every instantiated cache. */
+    async close() {
+        const all = Array.from(this.instances.values());
+        this.instances.clear();
+        await Promise.all(all.map((c) => c.close?.().catch(() => undefined)));
+    }
+    pluginIdFor(name) {
+        const path = `actor-ts.cache.${name}.plugin`;
+        return this.system.config.hasPath(path)
+            ? this.system.config.getString(path)
+            : ConfigKeys.cache.inMemory;
+    }
+}
+export const CacheExtensionId = extensionId('CacheExtension', (system) => new CacheExtension(system));
+// Public plugin-id exports — kept for back-compat with downstream code.
+// Source-of-truth is `ConfigKeys.cache.*`; these are aliases.
+export const REDIS_CACHE_PLUGIN_ID = ConfigKeys.cache.redis;
+export const MEMCACHED_CACHE_PLUGIN_ID = ConfigKeys.cache.memcached;
+export const IN_MEMORY_CACHE_PLUGIN_ID = ConfigKeys.cache.inMemory;
+//# sourceMappingURL=CacheExtension.js.map

package/dist/cache/CacheExtension.js.map

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

package/dist/cache/InMemoryCache.d.ts

@@ -0,0 +1,16 @@
+import { type Option } from '../util/Option.js';
+import type { Cache } from './Cache.js';
+export declare class InMemoryCache implements Cache {
+    private readonly store;
+    get<V>(key: string): Promise<Option<V>>;
+    set<V>(key: string, value: V, ttlMs?: number): Promise<void>;
+    incr(key: string, ttlMs?: number): Promise<number>;
+    setIfAbsent<V>(key: string, value: V, ttlMs?: number): Promise<boolean>;
+    delete(...keys: string[]): Promise<void>;
+    mget<V>(keys: ReadonlyArray<string>): Promise<Map<string, V>>;
+    mset<V>(entries: ReadonlyMap<string, V>, ttlMs?: number): Promise<void>;
+    close(): Promise<void>;
+    /** Test hook — current entry count, including expired-but-not-cleaned entries. */
+    sizeForTest(): number;
+}
+//# sourceMappingURL=InMemoryCache.d.ts.map

package/dist/cache/InMemoryCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemoryCache.d.ts","sourceRoot":"","sources":["../../src/cache/InMemoryCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAkBxC,qBAAa,aAAc,YAAW,KAAK;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAE5C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAUvC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlD,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvE,MAAM,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAe7D,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,kFAAkF;IAClF,WAAW,IAAI,MAAM;CACtB"}

package/dist/cache/InMemoryCache.js

@@ -0,0 +1,86 @@
+import { none, some } from '../util/Option.js';
+export class InMemoryCache {
+    store = new Map();
+    async get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return none;
+        if (entry.expiresAt <= Date.now()) {
+            this.store.delete(key);
+            return none;
+        }
+        return some(entry.value);
+    }
+    async set(key, value, ttlMs) {
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new Error(`InMemoryCache.set: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const expiresAt = ttlMs === undefined ? Infinity : Date.now() + ttlMs;
+        this.store.set(key, { value, expiresAt });
+    }
+    async incr(key, ttlMs) {
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new Error(`InMemoryCache.incr: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const now = Date.now();
+        const entry = this.store.get(key);
+        if (!entry || entry.expiresAt <= now) {
+            // Fresh counter — set TTL only on creation, matching Redis semantics.
+            const expiresAt = ttlMs === undefined ? Infinity : now + ttlMs;
+            this.store.set(key, { value: 1, expiresAt });
+            return 1;
+        }
+        if (typeof entry.value !== 'number') {
+            throw new Error(`InMemoryCache.incr: key '${key}' holds a non-numeric value (${typeof entry.value})`);
+        }
+        const next = entry.value + 1;
+        entry.value = next;
+        return next;
+    }
+    async setIfAbsent(key, value, ttlMs) {
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new Error(`InMemoryCache.setIfAbsent: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const now = Date.now();
+        const entry = this.store.get(key);
+        if (entry && entry.expiresAt > now)
+            return false;
+        const expiresAt = ttlMs === undefined ? Infinity : now + ttlMs;
+        this.store.set(key, { value, expiresAt });
+        return true;
+    }
+    async delete(...keys) {
+        for (const k of keys)
+            this.store.delete(k);
+    }
+    async mget(keys) {
+        const out = new Map();
+        const now = Date.now();
+        for (const k of keys) {
+            const entry = this.store.get(k);
+            if (!entry)
+                continue;
+            if (entry.expiresAt <= now) {
+                this.store.delete(k); // lazy-expire matches `get` semantics
+                continue;
+            }
+            out.set(k, entry.value);
+        }
+        return out;
+    }
+    async mset(entries, ttlMs) {
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new Error(`InMemoryCache.mset: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const expiresAt = ttlMs === undefined ? Infinity : Date.now() + ttlMs;
+        for (const [k, v] of entries) {
+            this.store.set(k, { value: v, expiresAt });
+        }
+    }
+    async close() {
+        this.store.clear();
+    }
+    /** Test hook — current entry count, including expired-but-not-cleaned entries. */
+    sizeForTest() { return this.store.size; }
+}
+//# sourceMappingURL=InMemoryCache.js.map

package/dist/cache/InMemoryCache.js.map

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