@spine-event-engine/delivery-server 2.0.0-snapshot.2

package/dist/bin/spine-delivery-server.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { DeliveryServer } from "../server/delivery-server.js";
+/**
+ * Provides process lifecycle handling for the delivery server executable.
+ */
+const DeliveryProcess = Object.freeze({
+    run: (server) => {
+        let stopping;
+        const removeSignalHandlers = () => {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+        };
+        const stop = () => {
+            stopping ??= server
+                .close()
+                .catch((error) => {
+                process.exitCode = 1;
+                process.stderr.write(`Delivery server shutdown failed: ${DeliveryProcess.errorMessage(error)}\n`);
+            })
+                .finally(removeSignalHandlers);
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        server.start().then((running) => {
+            process.stdout.write(`Delivery server listening at ${running.baseUrl}\n`);
+        }, (error) => {
+            process.exitCode = 1;
+            process.stderr.write(`Delivery server startup failed: ${DeliveryProcess.errorMessage(error)}\n`);
+            removeSignalHandlers();
+        });
+    },
+    errorMessage: (error) => error instanceof Error ? error.message : "unknown error",
+});
+try {
+    DeliveryProcess.run(new DeliveryServer());
+}
+catch (error) {
+    process.exitCode = 1;
+    process.stderr.write(`Delivery server startup failed: ${DeliveryProcess.errorMessage(error)}\n`);
+}
+//# sourceMappingURL=spine-delivery-server.js.map

package/dist/bin/spine-delivery-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine-delivery-server.js","sourceRoot":"","sources":["../../src/bin/spine-delivery-server.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9D;;GAEG;AACH,MAAM,eAAe,GAkBhB,MAAM,CAAC,MAAM,CAAC;IACjB,GAAG,EAAE,CAAC,MAAsB,EAAQ,EAAE;QACpC,IAAI,QAAmC,CAAC;QACxC,MAAM,oBAAoB,GAAG,GAAG,EAAE;YAChC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC,CAAC;QACF,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,QAAQ,KAAK,MAAM;iBAChB,KAAK,EAAE;iBACP,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACxB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;gBACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,oCAAoC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAC5E,CAAC;YACJ,CAAC,CAAC;iBACD,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACnC,CAAC,CAAC;QAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC3B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CACjB,CAAC,OAAO,EAAE,EAAE;YACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QAC5E,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mCAAmC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAC3E,CAAC;YACF,oBAAoB,EAAE,CAAC;QACzB,CAAC,CACF,CAAC;IACJ,CAAC;IACD,YAAY,EAAE,CAAC,KAAc,EAAU,EAAE,CACvC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;CAC3D,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,eAAe,CAAC,GAAG,CAAC,IAAI,cAAc,EAAE,CAAC,CAAC;AAC5C,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACf,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACrB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mCAAmC,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACnG,CAAC"}

package/dist/core/in-memory-delivery-core.d.ts

@@ -0,0 +1,56 @@
+import type { ServiceImpl } from "@connectrpc/connect";
+import { InboxService, ShardService } from "@spine-event-engine/proto/delivery-server";
+/**
+ * Configures the listener-free in-memory delivery core.
+ */
+export interface DeliveryCoreOptions {
+    /**
+     * Automatic pickup expiry; zero disables automatic stale takeover.
+     */
+    readonly processingTimeoutMs?: number;
+    /**
+     * Returns a deterministic wall-clock value in Unix milliseconds.
+     *
+     * @returns Provides the current Unix time in milliseconds.
+     */
+    readonly now?: () => number;
+    /**
+     * Maximum retained records; integer from 1 through 2,147,483,647.
+     */
+    readonly maxRetainedMessages?: number;
+    /**
+     * Maximum retained serialized record bytes; integer from 1 through 2,147,483,647.
+     */
+    readonly maxRetainedBytes?: number;
+    /**
+     * Maximum tracked shards; integer from 1 through 1,000.
+     */
+    readonly maxTrackedShards?: number;
+}
+/**
+ * Provides handler implementations for caller-owned Connect router registration.
+ */
+export interface DeliveryCore {
+    /**
+     * Serves Inbox RPCs.
+     */
+    readonly inbox: ServiceImpl<typeof InboxService>;
+    /**
+     * Serves Shard RPCs.
+     */
+    readonly shards: ServiceImpl<typeof ShardService>;
+}
+/**
+ * Creates listener-free in-memory delivery cores.
+ */
+export declare const InMemoryDelivery: Readonly<{
+    /**
+     * Creates an empty Inbox and Shard core.
+     *
+     * @param options Configures state limits and stale pickup expiry.
+     * @returns Provides the handlers without owning a listener or process lifecycle.
+     * @throws {RangeError} When the processing timeout is not a finite non-negative number.
+     */
+    create(options?: DeliveryCoreOptions): DeliveryCore;
+}>;
+//# sourceMappingURL=in-memory-delivery-core.d.ts.map

package/dist/core/in-memory-delivery-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-delivery-core.d.ts","sourceRoot":"","sources":["../../src/core/in-memory-delivery-core.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAOvF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAG3B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;IAEjD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;CACnD;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC;IAGtC;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAAC;CACrD,CAsBC,CAAC"}

package/dist/core/in-memory-delivery-core.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { InboxService, ShardService } from "@spine-event-engine/proto/delivery-server";
+import { InboxHandlers } from "./inbox-service.js";
+import { InMemoryDeliveryState } from "./in-memory-delivery-state.js";
+import { MutationAdmission } from "./mutation-admission.js";
+import { ShardHandlers } from "./shard-service.js";
+/**
+ * Creates listener-free in-memory delivery cores.
+ */
+export const InMemoryDelivery = Object.freeze({
+    // prettier-ignore
+    /**
+     * Creates an empty Inbox and Shard core.
+     *
+     * @param options Configures state limits and stale pickup expiry.
+     * @returns Provides the handlers without owning a listener or process lifecycle.
+     * @throws {RangeError} When the processing timeout is not a finite non-negative number.
+     */
+    create(options = {}) {
+        const timeout = options.processingTimeoutMs ?? 0;
+        if (!Number.isFinite(timeout) || timeout < 0)
+            throw new RangeError("Processing timeout is invalid.");
+        const state = new InMemoryDeliveryState(options);
+        const admission = new MutationAdmission();
+        const now = options.now ?? Date.now;
+        return Object.freeze({
+            inbox: InboxHandlers.create(state, admission),
+            shards: ShardHandlers.create(state, admission, now, timeout),
+        });
+    },
+});
+//# sourceMappingURL=in-memory-delivery-core.js.map

package/dist/core/in-memory-delivery-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-delivery-core.js","sourceRoot":"","sources":["../../src/core/in-memory-delivery-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAEvF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAqDnD;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAWxB,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,UAA+B,EAAE;QACtC,MAAM,OAAO,GAAG,OAAO,CAAC,mBAAmB,IAAI,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;YAC1C,MAAM,IAAI,UAAU,CAAC,gCAAgC,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,IAAI,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,IAAI,iBAAiB,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;QACpC,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC;YAC7C,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC"}

package/dist/core/in-memory-delivery-state.d.ts

@@ -0,0 +1,86 @@
+import { type InboxMessage, type ShardIndex, type WorkerId } from "@spine-event-engine/proto/delivery";
+import { type DeliveryStateLimits } from "./limits.js";
+/**
+ * Represents retained pickup state for one delivery shard.
+ */
+export interface ShardRecord {
+    /**
+     * Identifies the tracked shard.
+     */
+    readonly shard: ShardIndex;
+    /**
+     * Identifies the current worker when picked.
+     */
+    readonly worker: WorkerId | undefined;
+    /**
+     * Records the pickup time in milliseconds.
+     */
+    readonly whenLastPicked: number | undefined;
+}
+/**
+ * Package-private canonical detached state; a new instance deliberately starts empty.
+ */
+export declare class InMemoryDeliveryState {
+    #private;
+    /**
+     * Stores messages by stable identity.
+     */
+    readonly messages: Map<string, InboxMessage>;
+    /**
+     * Stores sessions by stable shard identity.
+     */
+    readonly shards: Map<string, ShardRecord>;
+    /**
+     * Creates empty state.
+     *
+     * @param limits Configures retained-state limits.
+     */
+    constructor(limits?: Partial<DeliveryStateLimits>);
+    /**
+     * Stores a validated batch atomically.
+     *
+     * @param messages Supplies encoded messages.
+     * @returns Lists newly inserted messages.
+     */
+    putAll(messages: readonly {
+        readonly message: InboxMessage;
+        readonly bytes: number;
+    }[]): InboxMessage[];
+    /**
+     * Deletes a message.
+     *
+     * @param message Identifies the message.
+     * @returns Reports whether the message existed.
+     */
+    delete(message: InboxMessage): boolean;
+    /**
+     * Finds an active shard session.
+     *
+     * @param shard Identifies the shard.
+     * @returns Provides the session when active.
+     */
+    session(shard: ShardIndex): ShardRecord | undefined;
+    /**
+     * Determines whether a shard has a retained `TO_DELIVER` message awaiting delivery.
+     *
+     * @param shard Identifies the shard to inspect.
+     * @returns Whether the shard has at least one retained `TO_DELIVER` message.
+     */
+    hasPending(shard: ShardIndex): boolean;
+    /**
+     * Stores a shard pickup session.
+     *
+     * @param shard Identifies the shard.
+     * @param worker Identifies the worker.
+     * @param whenPicked Records the pickup time.
+     */
+    setSession(shard: ShardIndex, worker: WorkerId, whenPicked: number): void;
+    /**
+     * Removes an active shard session.
+     *
+     * @param shard Identifies the shard.
+     * @returns Provides the former session when active.
+     */
+    release(shard: ShardIndex): ShardRecord | undefined;
+}
+//# sourceMappingURL=in-memory-delivery-state.d.ts.map

package/dist/core/in-memory-delivery-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-delivery-state.d.ts","sourceRoot":"","sources":["../../src/core/in-memory-delivery-state.ts"],"names":[],"mappings":"AAeA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,QAAQ,EACd,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvE;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED;;GAEG;AACH,qBAAa,qBAAqB;;IAGhC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAmC;IAE/E;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAkC;IAO3E;;;;OAIG;gBACS,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAIrD;;;;;OAKG;IACH,MAAM,CACJ,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,GAC9E,YAAY,EAAE;IAgBjB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAatC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS;IAKnD;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;IAItC;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IASzE;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS;CAuFpD"}

package/dist/core/in-memory-delivery-state.js

@@ -0,0 +1,214 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+import { InboxMessageStatus, } from "@spine-event-engine/proto/delivery";
+import { DeliveryLimits } from "./limits.js";
+import { DeliveryMessages, DeliveryShards, DeliveryWorkers } from "./wire-values.js";
+/**
+ * Package-private canonical detached state; a new instance deliberately starts empty.
+ */
+export class InMemoryDeliveryState {
+    // prettier-ignore
+    /**
+     * Stores messages by stable identity.
+     */
+    messages = new Map();
+    /**
+     * Stores sessions by stable shard identity.
+     */
+    shards = new Map();
+    #messageBytes = new Map();
+    #messageShards = new Map();
+    #deliverableShards = new Map();
+    #limits;
+    #retainedBytes = 0;
+    /**
+     * Creates empty state.
+     *
+     * @param limits Configures retained-state limits.
+     */
+    constructor(limits = {}) {
+        this.#limits = DeliveryLimits.resolve(limits);
+    }
+    /**
+     * Stores a validated batch atomically.
+     *
+     * @param messages Supplies encoded messages.
+     * @returns Lists newly inserted messages.
+     */
+    putAll(messages) {
+        this.#ensureCapacity(messages);
+        const initial = new Set(this.messages.keys());
+        const inserted = [];
+        const seen = new Set();
+        const final = new Map();
+        for (const candidate of messages) {
+            const key = DeliveryMessages.key(candidate.message);
+            if (!initial.has(key) && !seen.has(key))
+                inserted.push(candidate.message);
+            seen.add(key);
+            final.set(key, candidate);
+        }
+        for (const [key, candidate] of final)
+            this.#replace(key, candidate.message, candidate.bytes);
+        return inserted;
+    }
+    /**
+     * Deletes a message.
+     *
+     * @param message Identifies the message.
+     * @returns Reports whether the message existed.
+     */
+    delete(message) {
+        const key = DeliveryMessages.key(message);
+        const current = this.messages.get(key);
+        if (current === undefined)
+            return false;
+        this.messages.delete(key);
+        this.#retainedBytes -= this.#messageBytes.get(key) ?? 0;
+        this.#messageBytes.delete(key);
+        this.#decrementMessageShard(current);
+        this.#decrementDeliverableShard(current);
+        this.#pruneReleasedShard(DeliveryShards.key(this.#requiredShard(current)));
+        return true;
+    }
+    /**
+     * Finds an active shard session.
+     *
+     * @param shard Identifies the shard.
+     * @returns Provides the session when active.
+     */
+    session(shard) {
+        const record = this.shards.get(DeliveryShards.key(shard));
+        return record?.worker === undefined ? undefined : record;
+    }
+    /**
+     * Determines whether a shard has a retained `TO_DELIVER` message awaiting delivery.
+     *
+     * @param shard Identifies the shard to inspect.
+     * @returns Whether the shard has at least one retained `TO_DELIVER` message.
+     */
+    hasPending(shard) {
+        return this.#deliverableShards.has(DeliveryShards.key(shard));
+    }
+    /**
+     * Stores a shard pickup session.
+     *
+     * @param shard Identifies the shard.
+     * @param worker Identifies the worker.
+     * @param whenPicked Records the pickup time.
+     */
+    setSession(shard, worker, whenPicked) {
+        this.#ensureShardCapacity(shard);
+        this.shards.set(DeliveryShards.key(shard), {
+            shard: DeliveryShards.copy(shard),
+            worker: DeliveryWorkers.copy(worker),
+            whenLastPicked: whenPicked,
+        });
+    }
+    /**
+     * Removes an active shard session.
+     *
+     * @param shard Identifies the shard.
+     * @returns Provides the former session when active.
+     */
+    release(shard) {
+        const key = DeliveryShards.key(shard);
+        const record = this.shards.get(key);
+        if (record?.worker === undefined)
+            return undefined;
+        if (this.#messageShards.has(key))
+            this.shards.set(key, { ...record, worker: undefined });
+        else
+            this.shards.delete(key);
+        return record;
+    }
+    #ensureCapacity(candidates) {
+        const final = new Map();
+        for (const candidate of candidates)
+            final.set(DeliveryMessages.key(candidate.message), candidate);
+        let count = this.messages.size;
+        let bytes = this.#retainedBytes;
+        const tracked = new Set([...this.shards.keys(), ...this.#messageShards.keys()]);
+        for (const [key, candidate] of final) {
+            const prior = this.messages.get(key);
+            if (prior === undefined)
+                count++;
+            else
+                bytes -= this.#messageBytes.get(key) ?? 0;
+            bytes += candidate.bytes;
+            tracked.add(DeliveryShards.key(this.#requiredShard(candidate.message)));
+        }
+        if (count > this.#limits.maxRetainedMessages ||
+            bytes > this.#limits.maxRetainedBytes ||
+            tracked.size > this.#limits.maxTrackedShards) {
+            throw new ConnectError("Delivery retained-state capacity is full.", Code.ResourceExhausted);
+        }
+    }
+    #replace(key, message, bytes) {
+        const prior = this.messages.get(key);
+        if (prior !== undefined) {
+            this.#retainedBytes -= this.#messageBytes.get(key) ?? 0;
+            this.#decrementMessageShard(prior);
+            this.#decrementDeliverableShard(prior);
+        }
+        this.messages.set(key, DeliveryMessages.copy(message));
+        this.#messageBytes.set(key, bytes);
+        this.#retainedBytes += bytes;
+        const shard = DeliveryShards.key(this.#requiredShard(message));
+        this.#messageShards.set(shard, (this.#messageShards.get(shard) ?? 0) + 1);
+        if (message.status === InboxMessageStatus.TO_DELIVER)
+            this.#deliverableShards.set(shard, (this.#deliverableShards.get(shard) ?? 0) + 1);
+    }
+    #decrementMessageShard(message) {
+        const key = DeliveryShards.key(this.#requiredShard(message));
+        const count = this.#messageShards.get(key);
+        if (count === undefined || count < 1)
+            throw new TypeError("Delivery message shard count is invalid.");
+        if (count === 1)
+            this.#messageShards.delete(key);
+        else
+            this.#messageShards.set(key, count - 1);
+    }
+    #decrementDeliverableShard(message) {
+        if (message.status !== InboxMessageStatus.TO_DELIVER)
+            return;
+        const key = DeliveryShards.key(this.#requiredShard(message));
+        const count = this.#deliverableShards.get(key);
+        if (count === undefined || count < 1)
+            throw new TypeError("Delivery deliverable shard count is invalid.");
+        if (count === 1)
+            this.#deliverableShards.delete(key);
+        else
+            this.#deliverableShards.set(key, count - 1);
+    }
+    #ensureShardCapacity(shard) {
+        const key = DeliveryShards.key(shard);
+        if (this.shards.has(key) || this.#messageShards.has(key))
+            return;
+        const tracked = new Set([...this.shards.keys(), ...this.#messageShards.keys()]);
+        if (tracked.size >= this.#limits.maxTrackedShards)
+            throw new ConnectError("Delivery tracked-shard capacity is full.", Code.ResourceExhausted);
+    }
+    #pruneReleasedShard(key) {
+        if (!this.#messageShards.has(key) && this.shards.get(key)?.worker === undefined)
+            this.shards.delete(key);
+    }
+    #requiredShard(message) {
+        if (message.id?.index === undefined)
+            throw new TypeError("Delivery message identity is missing.");
+        return message.id.index;
+    }
+}
+//# sourceMappingURL=in-memory-delivery-state.js.map

package/dist/core/in-memory-delivery-state.js.map

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

package/dist/core/inbox-service.d.ts

@@ -0,0 +1,20 @@
+import { type ServiceImpl } from "@connectrpc/connect";
+import { InboxService } from "@spine-event-engine/proto/delivery-server";
+import { type ShardIndex } from "@spine-event-engine/proto/delivery";
+import { InMemoryDeliveryState } from "./in-memory-delivery-state.js";
+import { MutationAdmission } from "./mutation-admission.js";
+/**
+ * Provides Inbox RPC handler implementations.
+ */
+export declare const InboxHandlers: Readonly<{
+    /**
+     * Creates Inbox RPC handlers.
+     *
+     * @param state Stores Inbox messages served by the handlers.
+     * @param admission Controls write admission and cancellation.
+     * @param onMessageTransition Observes retained-message count transitions.
+     * @returns The Inbox service implementation.
+     */
+    create: (state: InMemoryDeliveryState, admission: MutationAdmission, onMessageTransition?: (shard: ShardIndex, delta: 1 | -1) => void) => ServiceImpl<typeof InboxService>;
+}>;
+//# sourceMappingURL=inbox-service.d.ts.map

package/dist/core/inbox-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-service.d.ts","sourceRoot":"","sources":["../../src/core/inbox-service.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EACL,YAAY,EAGb,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAOtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG5D;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC;IAGnC;;;;;;;OAOG;IACH,MAAM,EAAE,CACN,KAAK,EAAE,qBAAqB,EAC5B,SAAS,EAAE,iBAAiB,EAC5B,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,KAC7D,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;CACvC,CAuGC,CAAC"}