actor-ts 0.9.0

package/dist/mailbox/BoundedMailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundedMailbox.d.ts","sourceRoot":"","sources":["../../src/mailbox/BoundedMailbox.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEhE,MAAM,MAAM,sBAAsB;AAChC,yEAAyE;AACvE,WAAW;AACb,uCAAuC;GACrC,UAAU;AACZ,wDAAwD;GACtD,QAAQ,CAAC;AAEb,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAC5C;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,QAAQ,EAAE,MAAM;CAI7B;AAED;;;GAGG;AACH,qBAAa,cAAc,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,8EAA8E;IAC9E,YAAY,SAAK;gBAEL,QAAQ,EAAE,sBAAsB;IAOnC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;CAezC"}

package/dist/mailbox/BoundedMailbox.js

@@ -0,0 +1,41 @@
+import { match } from 'ts-pattern';
+import { Mailbox } from '../internal/Mailbox.js';
+export class MailboxFullError extends Error {
+    constructor(capacity) {
+        super(`bounded mailbox full (capacity=${capacity})`);
+        this.name = 'MailboxFullError';
+    }
+}
+/**
+ * Mailbox with a fixed upper bound on queued user messages.  Policy for
+ * what happens when a message arrives on a full mailbox is configurable.
+ */
+export class BoundedMailbox extends Mailbox {
+    capacity;
+    overflow;
+    /** Number of messages dropped by the overflow policy — useful for metrics. */
+    droppedCount = 0;
+    constructor(settings) {
+        super();
+        if (settings.capacity < 1)
+            throw new Error('BoundedMailbox: capacity must be >= 1');
+        this.capacity = settings.capacity;
+        this.overflow = settings.overflow ?? 'reject';
+    }
+    enqueue(env) {
+        if (this.size >= this.capacity) {
+            match(this.overflow)
+                .with('drop-head', () => {
+                super.dequeueUser();
+                this.droppedCount++;
+                super.enqueue(env);
+            })
+                .with('drop-new', () => { this.droppedCount++; })
+                .with('reject', () => { throw new MailboxFullError(this.capacity); })
+                .exhaustive();
+            return;
+        }
+        super.enqueue(env);
+    }
+}
+//# sourceMappingURL=BoundedMailbox.js.map

package/dist/mailbox/BoundedMailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundedMailbox.js","sourceRoot":"","sources":["../../src/mailbox/BoundedMailbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,OAAO,EAAiB,MAAM,wBAAwB,CAAC;AAehE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,YAAY,QAAgB;QAC1B,KAAK,CAAC,kCAAkC,QAAQ,GAAG,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,cAA4B,SAAQ,OAAU;IACxC,QAAQ,CAAS;IACjB,QAAQ,CAAyB;IAClD,8EAA8E;IAC9E,YAAY,GAAG,CAAC,CAAC;IAEjB,YAAY,QAAgC;QAC1C,KAAK,EAAE,CAAC;QACR,IAAI,QAAQ,CAAC,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACpF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC;IAChD,CAAC;IAEQ,OAAO,CAAC,GAAgB;QAC/B,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;iBACjB,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;gBACtB,KAAK,CAAC,WAAW,EAAE,CAAC;gBACpB,IAAI,CAAC,YAAY,EAAE,CAAC;gBACpB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC,CAAC;iBACD,IAAI,CAAC,UAAU,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;iBAChD,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,MAAM,IAAI,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;iBACpE,UAAU,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;CACF"}

package/dist/mailbox/PriorityMailbox.d.ts

@@ -0,0 +1,32 @@
+import { Mailbox, type Envelope } from '../internal/Mailbox.js';
+/**
+ * Priority order for user messages.  Lower numeric priority values are
+ * dequeued first — `0` is highest priority.  Ties are broken by FIFO
+ * insertion order.
+ */
+export type PriorityFunction<T> = (message: T) => number;
+export interface PriorityMailboxSettings<T> {
+    readonly priorityFor: PriorityFunction<T>;
+}
+/**
+ * User messages are dequeued in priority order (ascending priority value,
+ * then FIFO).  System messages still take strict precedence over any user
+ * message.  Internally backed by an ordered array — suitable for moderate
+ * mailbox sizes; swap for a heap if throughput becomes a concern.
+ */
+export declare class PriorityMailbox<T = unknown> extends Mailbox<T> {
+    private readonly priorityFor;
+    /** Monotonic counter — tie-breaker preserving FIFO among equal-priority messages. */
+    private seq;
+    private readonly ordered;
+    constructor(settings: PriorityMailboxSettings<T>);
+    enqueue(env: Envelope<T>): void;
+    dequeueUser(): Envelope<T> | undefined;
+    get size(): number;
+    hasUserMessages(): boolean;
+    drainUser(): Envelope<T>[];
+    prependUser(envs: Array<Envelope<T>>): void;
+    /** Peek at the next message that would be dequeued, without removing it. */
+    hasMessages(): boolean;
+}
+//# sourceMappingURL=PriorityMailbox.d.ts.map

package/dist/mailbox/PriorityMailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PriorityMailbox.d.ts","sourceRoot":"","sources":["../../src/mailbox/PriorityMailbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,CAAC;AAEzD,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC3C;AAED;;;;;GAKG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsB;IAClD,qFAAqF;IACrF,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkE;gBAE9E,QAAQ,EAAE,uBAAuB,CAAC,CAAC,CAAC;IAKvC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;IAkB/B,WAAW,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS;IAK/C,IAAa,IAAI,IAAI,MAAM,CAAgC;IAElD,eAAe,IAAI,OAAO;IAE1B,SAAS,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE;IAM1B,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAMpD,4EAA4E;IACnE,WAAW,IAAI,OAAO;CAGhC"}

package/dist/mailbox/PriorityMailbox.js

@@ -0,0 +1,58 @@
+import { Mailbox } from '../internal/Mailbox.js';
+/**
+ * User messages are dequeued in priority order (ascending priority value,
+ * then FIFO).  System messages still take strict precedence over any user
+ * message.  Internally backed by an ordered array — suitable for moderate
+ * mailbox sizes; swap for a heap if throughput becomes a concern.
+ */
+export class PriorityMailbox extends Mailbox {
+    priorityFor;
+    /** Monotonic counter — tie-breaker preserving FIFO among equal-priority messages. */
+    seq = 0;
+    ordered = [];
+    constructor(settings) {
+        super();
+        this.priorityFor = settings.priorityFor;
+    }
+    enqueue(env) {
+        const priority = this.priorityFor(env.message);
+        const entry = { env, priority, seq: this.seq++ };
+        // Insert by priority, then seq.  Binary-search insertion — O(log n)
+        // locate + O(n) splice, adequate for moderate queues.
+        let lo = 0, hi = this.ordered.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >>> 1;
+            const item = this.ordered[mid];
+            if (item.priority < priority || (item.priority === priority && item.seq < entry.seq)) {
+                lo = mid + 1;
+            }
+            else {
+                hi = mid;
+            }
+        }
+        this.ordered.splice(lo, 0, entry);
+    }
+    dequeueUser() {
+        if (this.suspended)
+            return undefined;
+        return this.ordered.shift()?.env;
+    }
+    get size() { return this.ordered.length; }
+    hasUserMessages() { return this.ordered.length > 0; }
+    drainUser() {
+        const out = this.ordered.map(e => e.env);
+        this.ordered.length = 0;
+        return out;
+    }
+    prependUser(envs) {
+        // Reinsert via enqueue — priority is re-computed, which is the correct
+        // behaviour (unstashed messages rejoin their priority tier).
+        for (const e of envs)
+            this.enqueue(e);
+    }
+    /** Peek at the next message that would be dequeued, without removing it. */
+    hasMessages() {
+        return this.hasSystemMessages() || (!this.suspended && this.ordered.length > 0);
+    }
+}
+//# sourceMappingURL=PriorityMailbox.js.map

package/dist/mailbox/PriorityMailbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PriorityMailbox.js","sourceRoot":"","sources":["../../src/mailbox/PriorityMailbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAiB,MAAM,wBAAwB,CAAC;AAahE;;;;;GAKG;AACH,MAAM,OAAO,eAA6B,SAAQ,OAAU;IACzC,WAAW,CAAsB;IAClD,qFAAqF;IAC7E,GAAG,GAAG,CAAC,CAAC;IACC,OAAO,GAA+D,EAAE,CAAC;IAE1F,YAAY,QAAoC;QAC9C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC;IAC1C,CAAC;IAEQ,OAAO,CAAC,GAAgB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACjD,oEAAoE;QACpE,sDAAsD;QACtD,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACrC,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAE,CAAC;YAChC,IAAI,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrF,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;YACf,CAAC;iBAAM,CAAC;gBACN,EAAE,GAAG,GAAG,CAAC;YACX,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IACpC,CAAC;IAEQ,WAAW;QAClB,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,SAAS,CAAC;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,GAAG,CAAC;IACnC,CAAC;IAED,IAAa,IAAI,KAAa,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAElD,eAAe,KAAc,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IAE9D,SAAS;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,OAAO,GAAG,CAAC;IACb,CAAC;IAEQ,WAAW,CAAC,IAAwB;QAC3C,uEAAuE;QACvE,6DAA6D;QAC7D,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IAED,4EAA4E;IACnE,WAAW;QAClB,OAAO,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClF,CAAC;CACF"}

package/dist/mailbox/index.d.ts

@@ -0,0 +1,5 @@
+export { BoundedMailbox, MailboxFullError } from './BoundedMailbox.js';
+export type { BoundedMailboxSettings, BoundedMailboxOverflow, } from './BoundedMailbox.js';
+export { PriorityMailbox } from './PriorityMailbox.js';
+export type { PriorityMailboxSettings, PriorityFunction, } from './PriorityMailbox.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mailbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mailbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvE,YAAY,EACV,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,YAAY,EACV,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC"}

package/dist/mailbox/index.js

@@ -0,0 +1,3 @@
+export { BoundedMailbox, MailboxFullError } from './BoundedMailbox.js';
+export { PriorityMailbox } from './PriorityMailbox.js';
+//# sourceMappingURL=index.js.map

package/dist/mailbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mailbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAKvE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/management/HealthCheck.d.ts

@@ -0,0 +1,21 @@
+/** Return value of a health check.  `status=true` means healthy. */
+export interface HealthCheckResult {
+    readonly name: string;
+    readonly status: boolean;
+    readonly detail?: string;
+}
+export type HealthCheckFn = () => Promise<HealthCheckResult> | HealthCheckResult;
+/**
+ * Thin registry for liveness / readiness style checks.  Components
+ * (persistence journal, sharding coordinator, …) register their own checks;
+ * the management endpoints aggregate them and surface the overall status.
+ */
+export declare class HealthCheckRegistry {
+    private readonly liveness;
+    private readonly readiness;
+    addLiveness(fn: HealthCheckFn): () => void;
+    addReadiness(fn: HealthCheckFn): () => void;
+    checkLiveness(): Promise<HealthCheckResult[]>;
+    checkReadiness(): Promise<HealthCheckResult[]>;
+}
+//# sourceMappingURL=HealthCheck.d.ts.map

package/dist/management/HealthCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthCheck.d.ts","sourceRoot":"","sources":["../../src/management/HealthCheck.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;AAEjF;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IAEjD,WAAW,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAQ1C,YAAY,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAQrC,aAAa,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAO7C,cAAc,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAMrD"}

package/dist/management/HealthCheck.js

@@ -0,0 +1,46 @@
+/**
+ * Thin registry for liveness / readiness style checks.  Components
+ * (persistence journal, sharding coordinator, …) register their own checks;
+ * the management endpoints aggregate them and surface the overall status.
+ */
+export class HealthCheckRegistry {
+    liveness = [];
+    readiness = [];
+    addLiveness(fn) {
+        this.liveness.push(fn);
+        return () => {
+            const i = this.liveness.indexOf(fn);
+            if (i >= 0)
+                this.liveness.splice(i, 1);
+        };
+    }
+    addReadiness(fn) {
+        this.readiness.push(fn);
+        return () => {
+            const i = this.readiness.indexOf(fn);
+            if (i >= 0)
+                this.readiness.splice(i, 1);
+        };
+    }
+    async checkLiveness() {
+        return Promise.all(this.liveness.map(async (fn) => {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                return { name: 'unknown', status: false, detail: String(err) };
+            }
+        }));
+    }
+    async checkReadiness() {
+        return Promise.all(this.readiness.map(async (fn) => {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                return { name: 'unknown', status: false, detail: String(err) };
+            }
+        }));
+    }
+}
+//# sourceMappingURL=HealthCheck.js.map

package/dist/management/HealthCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HealthCheck.js","sourceRoot":"","sources":["../../src/management/HealthCheck.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IACb,QAAQ,GAAoB,EAAE,CAAC;IAC/B,SAAS,GAAoB,EAAE,CAAC;IAEjD,WAAW,CAAC,EAAiB;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,EAAiB;QAC5B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1C,CAAC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,aAAa;QACjB,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YAChD,IAAI,CAAC;gBAAC,OAAO,MAAM,EAAE,EAAE,CAAC;YAAC,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAAC,CAAC;QACjF,CAAC,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,cAAc;QAClB,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;YACjD,IAAI,CAAC;gBAAC,OAAO,MAAM,EAAE,EAAE,CAAC;YAAC,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC;gBAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAAC,CAAC;QACjF,CAAC,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

package/dist/management/HttpManagement.d.ts

@@ -0,0 +1,43 @@
+import type { ActorSystem } from '../ActorSystem.js';
+import type { Cluster } from '../cluster/Cluster.js';
+import { type Route } from '../http/index.js';
+import type { HealthCheckResult } from './HealthCheck.js';
+import { HealthCheckRegistry } from './HealthCheck.js';
+export interface ManagementRoutesSettings {
+    /** Set to true to allow POST /cluster/leave (requires cluster). */
+    readonly enableLeaveEndpoint?: boolean;
+    /**
+     * Set to true to allow POST /cluster/down (#56).  Operator-initiated
+     * force-down of a remote member by address.  Off by default —
+     * production deployments typically gate this behind an auth proxy
+     * because it's a destructive action.
+     */
+    readonly enableDownEndpoint?: boolean;
+    /**
+     * Set to true to expose `GET /metrics` in Prometheus text format
+     * (#56).  Reads from the system's `MetricsRegistry`.  Off by default
+     * because most deployments scrape metrics from a separate port.
+     */
+    readonly enableMetricsEndpoint?: boolean;
+}
+/**
+ * Build a Route tree exposing cluster-management HTTP endpoints.  The
+ * caller binds the returned routes into their HTTP server — management
+ * usually lives on a separate port so it can be firewalled off the public one.
+ *
+ * Endpoints:
+ *   - `GET /cluster/members`                  →  current membership JSON
+ *   - `GET /cluster/leader`                   →  leader info
+ *   - `GET /cluster/shards?type=<typeName>`   →  shard-to-region map for one type (#56)
+ *   - `GET /health`                           →  liveness (200 iff all checks pass)
+ *   - `GET /ready`                            →  readiness (200 iff cluster is up + all checks pass)
+ *   - `POST /cluster/leave`                   →  graceful leave (optional, off by default)
+ *   - `POST /cluster/down`  body `{address}`  →  force-down a peer (optional, off by default) (#56)
+ *   - `GET /metrics`                          →  Prometheus text format (optional, off by default) (#56)
+ */
+export declare function managementRoutes(system: ActorSystem, cluster: Cluster | null, settings?: ManagementRoutesSettings): {
+    routes: Route;
+    health: HealthCheckRegistry;
+};
+export declare function isHealthy(results: HealthCheckResult[]): boolean;
+//# sourceMappingURL=HttpManagement.d.ts.map

package/dist/management/HttpManagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpManagement.d.ts","sourceRoot":"","sources":["../../src/management/HttpManagement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,OAAO,EAQL,KAAK,KAAK,EACX,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,QAAQ,GAAE,wBAA6B,GACtC;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CA+JhD;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAE/D"}

package/dist/management/HttpManagement.js

@@ -0,0 +1,158 @@
+import { DistributedDataId } from '../crdt/DistributedData.js';
+import { complete, completeJson, concat, get, path, post, Status, } from '../http/index.js';
+import { exportPrometheus } from '../metrics/PrometheusExporter.js';
+import { metricsOf } from '../metrics/MetricsExtension.js';
+import { HealthCheckRegistry } from './HealthCheck.js';
+/**
+ * Build a Route tree exposing cluster-management HTTP endpoints.  The
+ * caller binds the returned routes into their HTTP server — management
+ * usually lives on a separate port so it can be firewalled off the public one.
+ *
+ * Endpoints:
+ *   - `GET /cluster/members`                  →  current membership JSON
+ *   - `GET /cluster/leader`                   →  leader info
+ *   - `GET /cluster/shards?type=<typeName>`   →  shard-to-region map for one type (#56)
+ *   - `GET /health`                           →  liveness (200 iff all checks pass)
+ *   - `GET /ready`                            →  readiness (200 iff cluster is up + all checks pass)
+ *   - `POST /cluster/leave`                   →  graceful leave (optional, off by default)
+ *   - `POST /cluster/down`  body `{address}`  →  force-down a peer (optional, off by default) (#56)
+ *   - `GET /metrics`                          →  Prometheus text format (optional, off by default) (#56)
+ */
+export function managementRoutes(system, cluster, settings = {}) {
+    const health = new HealthCheckRegistry();
+    const clusterMembers = get(async () => {
+        if (!cluster)
+            return complete(Status.ServiceUnavailable, 'no cluster');
+        return completeJson(Status.OK, {
+            members: cluster.getMembers().map((m) => ({
+                address: m.address.toString(),
+                status: m.status,
+                version: m.version,
+                roles: Array.from(m.roles),
+            })),
+            self: cluster.selfAddress.toString(),
+        });
+    });
+    const clusterLeader = get(async () => {
+        if (!cluster)
+            return complete(Status.ServiceUnavailable, 'no cluster');
+        const l = cluster.leader();
+        return completeJson(Status.OK, {
+            leader: l.fold(() => null, (m) => m.address.toString()),
+            isSelf: l.exists((m) => m.address.equals(cluster.selfAddress)),
+        });
+    });
+    const liveness = get(async () => {
+        const results = await health.checkLiveness();
+        const ok = results.every((r) => r.status);
+        return completeJson(ok ? Status.OK : Status.ServiceUnavailable, {
+            status: ok ? 'UP' : 'DOWN',
+            checks: results,
+        });
+    });
+    const readiness = get(async () => {
+        const results = await health.checkReadiness();
+        const clusterReady = cluster
+            ? cluster.getMembers().some((m) => m.address.equals(cluster.selfAddress) && m.status === 'up')
+            : true;
+        const ok = clusterReady && results.every((r) => r.status);
+        return completeJson(ok ? Status.OK : Status.ServiceUnavailable, {
+            status: ok ? 'UP' : 'DOWN',
+            clusterReady,
+            checks: results,
+        });
+    });
+    const leaveRoute = settings.enableLeaveEndpoint && cluster
+        ? post(async () => {
+            // Fire-and-forget leave — the caller typically uses this as a PreStop
+            // hook and doesn't wait for completion in-request.  We do await one
+            // microtask so the intent is registered before returning 202.
+            void cluster.leave();
+            return complete(Status.Accepted, 'leaving');
+        })
+        : get(async () => complete(Status.NotFound, 'leave endpoint disabled'));
+    /**
+     * GET /cluster/shards?type=<typeName> — returns the current shard map
+     * for one sharded type as recorded by the coordinator in DistributedData.
+     * Backed by the same store the coordinator reads on leader failover
+     * (`sharding-coordinator-state|<typeName>`), so the view is at most
+     * one gossip-tick stale.  Returns 404 if DD isn't started or the
+     * type isn't known.
+     */
+    const clusterShards = get(async (req) => {
+        if (!cluster)
+            return complete(Status.ServiceUnavailable, 'no cluster');
+        const typeRaw = req.query['type'];
+        const typeName = Array.isArray(typeRaw) ? typeRaw[0] : typeRaw;
+        if (!typeName) {
+            return complete(Status.BadRequest, 'missing query param `type`');
+        }
+        const dd = system.extension(DistributedDataId);
+        if (!dd.isStarted()) {
+            return complete(Status.NotFound, 'DistributedData not started — shard map unavailable');
+        }
+        const reg = dd.get().get(`sharding-coordinator-state|${typeName}`);
+        const state = reg?.value();
+        if (!state) {
+            return complete(Status.NotFound, `no shard-map recorded for type "${typeName}" yet`);
+        }
+        return completeJson(Status.OK, {
+            typeName,
+            leader: state.leader,
+            takenAt: state.takenAt,
+            regions: state.regions.map((r) => ({
+                key: r.key,
+                address: `${r.node.systemName}@${r.node.host}:${r.node.port}`,
+                path: r.path,
+                proxy: r.proxy,
+                shards: r.shards,
+            })),
+            shardHome: state.shardHome.map(([shard, regionKey]) => ({ shard, regionKey })),
+        });
+    });
+    /**
+     * POST /cluster/down — operator-initiated force-down.  Request body
+     * must be JSON `{ "address": "<system>@<host>:<port>" }`.  Returns
+     * 202 if the member was downed, 404 if the address is unknown or
+     * already terminal.  Disabled by default; flip `enableDownEndpoint`
+     * after auth has been wired up at the proxy/ingress layer.
+     */
+    const downRoute = settings.enableDownEndpoint && cluster
+        ? post(async (req) => {
+            if (!req.body)
+                return complete(Status.BadRequest, 'missing JSON body');
+            let parsed;
+            try {
+                parsed = JSON.parse(new TextDecoder().decode(req.body));
+            }
+            catch (e) {
+                return complete(Status.BadRequest, `invalid JSON: ${e.message}`);
+            }
+            if (!parsed.address || typeof parsed.address !== 'string') {
+                return complete(Status.BadRequest, 'body must contain a string `address` field');
+            }
+            const ok = cluster.down(parsed.address);
+            return ok
+                ? completeJson(Status.Accepted, { downed: parsed.address })
+                : complete(Status.NotFound, `no member at ${parsed.address}`);
+        })
+        : get(async () => complete(Status.NotFound, 'down endpoint disabled'));
+    /** GET /metrics — Prometheus text format. */
+    const metricsRoute = settings.enableMetricsEndpoint
+        ? get(async () => ({
+            status: Status.OK,
+            body: exportPrometheus(metricsOf(system)),
+            contentType: 'text/plain; version=0.0.4; charset=utf-8',
+        }))
+        : get(async () => complete(Status.NotFound, 'metrics endpoint disabled'));
+    const routes = path('cluster', concat(path('members', clusterMembers), path('leader', clusterLeader), path('shards', clusterShards), path('leave', leaveRoute), path('down', downRoute)));
+    // Compose with the top-level health endpoints.
+    const all = concat(routes, path('health', liveness), path('ready', readiness), path('metrics', metricsRoute));
+    // Suppress unused warning in case the caller doesn't use the system reference.
+    void system;
+    return { routes: all, health };
+}
+export function isHealthy(results) {
+    return results.every((r) => r.status);
+}
+//# sourceMappingURL=HttpManagement.js.map

package/dist/management/HttpManagement.js.map

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

package/dist/management/index.d.ts

@@ -0,0 +1,5 @@
+export { managementRoutes, isHealthy } from './HttpManagement.js';
+export type { ManagementRoutesSettings } from './HttpManagement.js';
+export { HealthCheckRegistry } from './HealthCheck.js';
+export type { HealthCheckFn, HealthCheckResult } from './HealthCheck.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/management/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/management/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAClE,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/management/index.js

@@ -0,0 +1,3 @@
+export { managementRoutes, isHealthy } from './HttpManagement.js';
+export { HealthCheckRegistry } from './HealthCheck.js';
+//# sourceMappingURL=index.js.map

package/dist/management/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/management/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/metrics/Metrics.d.ts

@@ -0,0 +1,142 @@
+/**
+ * In-process metrics primitives for the actor framework (#11).
+ *
+ * Three classic types:
+ *
+ *   - **Counter** — monotonic, only goes up.  Page views, messages
+ *     delivered, restart counts.
+ *   - **Gauge** — settable / inc/dec.  Mailbox depth, members up,
+ *     active connections.
+ *   - **Histogram** — fixed buckets + sum + count.  Persist latency,
+ *     handler duration.  Bucket boundaries are upper-inclusive
+ *     (`le="0.005"` matches the Prometheus convention).
+ *
+ * Metrics carry **labels** — key/value tag pairs that turn one metric
+ * into many time series.  A `MetricsRegistry.counter('foo')` with no
+ * labels has one series; with `{node: 'n-1'}` you get one series per
+ * distinct value of `node`.
+ *
+ * Cardinality discipline is the user's responsibility — high-cardinality
+ * labels (request id, user id, …) will OOM your monitoring system.  The
+ * registry doesn't enforce limits; it'll happily create one series per
+ * combo you ask for.
+ *
+ * Exposition format is decoupled — see {@link PrometheusExporter} for
+ * the Prometheus 0.0.4 text format implementation.
+ */
+export type LabelValue = string | number | boolean;
+export type Labels = Readonly<Record<string, LabelValue>>;
+/**
+ * A single point-in-time observation of one metric series.  Exporters
+ * walk the registry and turn each sample into their wire format.
+ */
+export interface MetricSample {
+    /** Family name — e.g. `actor_messages_delivered_total`. */
+    readonly name: string;
+    /** Free-form description for `# HELP`. */
+    readonly help: string;
+    /** `'counter'`, `'gauge'`, `'histogram'`. */
+    readonly kind: 'counter' | 'gauge' | 'histogram';
+    /** Series-level labels.  Empty object for unlabeled series. */
+    readonly labels: Labels;
+    /** Counter / gauge value, or histogram sum (when `bucket` is set). */
+    readonly value: number;
+    /**
+     * Histogram bucket upper bound.  When set, `value` carries the
+     * cumulative count for that bucket; series name will be suffixed
+     * with `_bucket` and labels will include `le=<bound>`.  Special
+     * value `Infinity` represents the `+Inf` bucket.
+     */
+    readonly bucket?: number;
+    /** For histograms: total observation count.  Series name `_count`. */
+    readonly count?: number;
+    /** For histograms: total observation sum.  Series name `_sum`. */
+    readonly sum?: number;
+}
+export interface Counter {
+    inc(delta?: number): void;
+    /** Read for testing — exporters use the registry's `collect()`. */
+    readonly value: number;
+}
+export interface Gauge {
+    set(value: number): void;
+    inc(delta?: number): void;
+    dec(delta?: number): void;
+    readonly value: number;
+}
+/**
+ * Default bucket boundaries — the Prometheus client-library defaults,
+ * which work well for short-tail latencies in the 5ms..10s range.
+ * Provide your own via `MetricsRegistry.histogram(..., { buckets })`
+ * for histograms that don't fit this shape (e.g. payload sizes).
+ */
+export declare const DEFAULT_HISTOGRAM_BUCKETS: ReadonlyArray<number>;
+export interface Histogram {
+    /** Record an observation in seconds (or whatever unit your buckets use). */
+    observe(value: number): void;
+    /** Internal — exporters read via the registry. */
+    readonly buckets: ReadonlyArray<number>;
+    readonly counts: ReadonlyArray<number>;
+    readonly sum: number;
+    readonly count: number;
+}
+export interface CounterOptions {
+    readonly help?: string;
+}
+export interface GaugeOptions {
+    readonly help?: string;
+}
+export interface HistogramOptions {
+    readonly help?: string;
+    /** Override the default bucket set.  Sorted automatically. */
+    readonly buckets?: ReadonlyArray<number>;
+}
+/**
+ * Collection of metric families bound to one ActorSystem.  Pluggable
+ * exporters (`PrometheusExporter`) walk `collect()` to produce wire
+ * format; tests use the typed `counter` / `gauge` / `histogram`
+ * accessors directly.
+ */
+export interface MetricsRegistry {
+    /**
+     * Get-or-create a counter family.  Same `(name, help)` returns the
+     * same family across calls; `labels` selects (or creates) a child
+     * series within it.
+     */
+    counter(name: string, labels?: Labels, opts?: CounterOptions): Counter;
+    gauge(name: string, labels?: Labels, opts?: GaugeOptions): Gauge;
+    histogram(name: string, labels?: Labels, opts?: HistogramOptions): Histogram;
+    /** Snapshot every series as a flat list of {@link MetricSample}s. */
+    collect(): ReadonlyArray<MetricSample>;
+    /** Wipe the registry — primarily for tests. */
+    clear(): void;
+}
+/**
+ * Default in-memory implementation.  Thread-safe by virtue of being
+ * single-threaded (Bun + Node both run JS on a single thread per
+ * Worker; metrics live on the main thread of an ActorSystem).
+ */
+export declare class DefaultMetricsRegistry implements MetricsRegistry {
+    private readonly families;
+    counter(name: string, labels?: Labels, opts?: CounterOptions): Counter;
+    gauge(name: string, labels?: Labels, opts?: GaugeOptions): Gauge;
+    histogram(name: string, labels?: Labels, opts?: HistogramOptions): Histogram;
+    collect(): ReadonlyArray<MetricSample>;
+    clear(): void;
+    private familyOf;
+    private childOf;
+}
+/**
+ * Zero-cost registry that throws nothing away but records nothing.
+ * Used as the default on `ActorSystem.metrics` so instrumentation
+ * sprinkled through the codebase pays nothing when metrics aren't
+ * enabled.
+ */
+export declare class NoopMetricsRegistry implements MetricsRegistry {
+    counter(): Counter;
+    gauge(): Gauge;
+    histogram(): Histogram;
+    collect(): ReadonlyArray<MetricSample>;
+    clear(): void;
+}
+//# sourceMappingURL=Metrics.d.ts.map

package/dist/metrics/Metrics.d.ts.map

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