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

package/dist/delivery/delivery-monitor.d.ts

@@ -0,0 +1,165 @@
+import type { InboxMessage } from "./inbox.js";
+import type { ShardIndex } from "./shard-index.js";
+/**
+ * Executes a monitor-selected asynchronous reception outcome.
+ */
+export interface ReceptionAction {
+    /**
+     * Executes the selected reception outcome.
+     *
+     * @returns A promise that settles when the outcome has completed.
+     */
+    execute(): Promise<void>;
+}
+/**
+ * Executes a monitor-selected pickup outcome.
+ */
+export interface PickUpAction {
+    /**
+     * Executes the selected pickup outcome.
+     *
+     * @returns A promise that settles when the outcome has completed.
+     */
+    execute(): Promise<void>;
+}
+/**
+ * Describes a failed dispatch of one Inbox message.
+ */
+export declare class FailedReception {
+    readonly message: InboxMessage;
+    readonly error: unknown;
+    private readonly mark;
+    private readonly repeat;
+    /**
+     * Creates facts and fallback actions for a failed reception.
+     *
+     * @param message The message whose dispatch failed.
+     * @param error The dispatch failure.
+     * @param mark Marks the message delivered under the current shard session.
+     * @param repeat Repeats dispatch once under the current shard session.
+     */
+    constructor(message: InboxMessage, error: unknown, mark: () => Promise<void>, repeat: () => Promise<void>);
+    /**
+     * Returns durable acknowledgement of the failed row.
+     *
+     * @returns The acknowledgement action.
+     */
+    markDelivered(): ReceptionAction;
+    /**
+     * Returns one immediate repeat of the failed dispatch.
+     *
+     * @returns The repeat-dispatch action.
+     */
+    repeatDispatching(): ReceptionAction;
+}
+/**
+ * Describes a failed shard acquisition.
+ */
+export declare class FailedPickUp {
+    readonly shard: ShardIndex;
+    readonly error: unknown;
+    /**
+     * Creates facts for a failed shard acquisition.
+     *
+     * @param shard The shard whose acquisition failed.
+     * @param error The acquisition failure.
+     */
+    constructor(shard: ShardIndex, error: unknown);
+    /**
+     * Returns a failed delivery result without acquiring ownership.
+     *
+     * @returns The failed-result action.
+     */
+    fail(): PickUpAction;
+}
+/**
+ * Describes a shard already owned by another worker.
+ */
+export declare class AlreadyPickedUp {
+    readonly shard: ShardIndex;
+    /**
+     * Creates facts for an already-owned shard.
+     *
+     * @param shard The shard already owned by another worker.
+     */
+    constructor(shard: ShardIndex);
+    /**
+     * Returns a skipped delivery result without acquiring ownership.
+     *
+     * @returns The skipped-result action.
+     */
+    skip(): PickUpAction;
+}
+/**
+ * Identifies a point at which a monitor can stop finite delivery.
+ */
+export type DeliveryStage = "DELIVERY" | "PAGE";
+/**
+ * Summarizes one completed finite delivery.
+ */
+export interface DeliveryStatistics {
+    /**
+     * Counts messages considered for endpoint dispatch.
+     */
+    readonly processed: number;
+    /**
+     * Counts messages durably acknowledged as delivered.
+     */
+    readonly delivered: number;
+    /**
+     * Counts dispatch or acknowledgement failures observed by the run.
+     */
+    readonly failed: number;
+}
+/**
+ * Controls finite delivery failure actions without scheduling retries.
+ *
+ * Subclasses can return direct values or promises from every hook. The default
+ * reception policy marks the failed row delivered so independent targets keep
+ * draining; it never persists attempts, receipts, markers, or quarantine data.
+ */
+export declare class DeliveryMonitor {
+    /**
+     * Checks whether delivery can continue after a lifecycle stage.
+     *
+     * @param stage The stage that has just been reached.
+     * @returns Whether the current finite delivery should continue.
+     */
+    shouldContinueAfter(stage: DeliveryStage): boolean | Promise<boolean>;
+    /**
+     * Handles successful shard ownership before Inbox reads begin.
+     *
+     * @param shard The owned shard about to drain.
+     * @returns A promise that settles after the hook completes.
+     */
+    onDeliveryStarted(shard: ShardIndex): void | Promise<void>;
+    /**
+     * Handles a delivery after shard ownership has been released.
+     *
+     * @param statistics The immutable result counts for the finished delivery.
+     * @returns A promise that settles after the hook completes.
+     */
+    onDeliveryCompleted(statistics: DeliveryStatistics): void | Promise<void>;
+    /**
+     * Returns an action after endpoint dispatch or acknowledgement fails.
+     *
+     * @param reception The failure facts and one-shot actions.
+     * @returns The selected asynchronous reception action.
+     */
+    onReceptionFailure(reception: FailedReception): ReceptionAction | Promise<ReceptionAction>;
+    /**
+     * Returns an action after shard acquisition fails.
+     *
+     * @param failure The failed acquisition facts.
+     * @returns The selected pickup action.
+     */
+    onShardPickUpFailure(failure: FailedPickUp): PickUpAction | Promise<PickUpAction>;
+    /**
+     * Returns an action when another worker already owns the shard.
+     *
+     * @param failure The already-owned shard facts.
+     * @returns The selected pickup action.
+     */
+    onShardAlreadyPicked(failure: AlreadyPickedUp): PickUpAction | Promise<PickUpAction>;
+}
+//# sourceMappingURL=delivery-monitor.d.ts.map

package/dist/delivery/delivery-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-monitor.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-monitor.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;GAEG;AACH,MAAM,WAAW,eAAe;IAG9B;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAG3B;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,eAAe;IAYxB,QAAQ,CAAC,OAAO,EAAE,YAAY;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB;;;;;;;OAOG;gBAEQ,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,OAAO,EACN,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACzB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAG9C;;;;OAIG;IACH,aAAa,IAAI,eAAe;IAIhC;;;;OAIG;IACH,iBAAiB,IAAI,eAAe;CAGrC;AAED;;GAEG;AACH,qBAAa,YAAY;IAUrB,QAAQ,CAAC,KAAK,EAAE,UAAU;IAC1B,QAAQ,CAAC,KAAK,EAAE,OAAO;IARzB;;;;;OAKG;gBAEQ,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,OAAO;IAGzB;;;;OAIG;IACH,IAAI,IAAI,YAAY;CAGrB;AAED;;GAEG;AACH,qBAAa,eAAe;IAQd,QAAQ,CAAC,KAAK,EAAE,UAAU;IALtC;;;;OAIG;gBACkB,KAAK,EAAE,UAAU;IAEtC;;;;OAIG;IACH,IAAI,IAAI,YAAY;CAGrB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAG1B;;;;;OAKG;IACH,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrE;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D;;;;;OAKG;IACH,mBAAmB,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzE;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,eAAe,GAAG,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAI1F;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAIjF;;;;;OAKG;IACH,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;CAGrF"}

package/dist/delivery/delivery-monitor.js

@@ -0,0 +1,168 @@
+/*
+ * 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.
+ */
+/**
+ * Describes a failed dispatch of one Inbox message.
+ */
+export class FailedReception {
+    message;
+    error;
+    mark;
+    repeat;
+    // prettier-ignore
+    /**
+     * Creates facts and fallback actions for a failed reception.
+     *
+     * @param message The message whose dispatch failed.
+     * @param error The dispatch failure.
+     * @param mark Marks the message delivered under the current shard session.
+     * @param repeat Repeats dispatch once under the current shard session.
+     */
+    constructor(message, error, mark, repeat) {
+        this.message = message;
+        this.error = error;
+        this.mark = mark;
+        this.repeat = repeat;
+    }
+    /**
+     * Returns durable acknowledgement of the failed row.
+     *
+     * @returns The acknowledgement action.
+     */
+    markDelivered() {
+        return Object.freeze({ execute: this.mark });
+    }
+    /**
+     * Returns one immediate repeat of the failed dispatch.
+     *
+     * @returns The repeat-dispatch action.
+     */
+    repeatDispatching() {
+        return Object.freeze({ execute: this.repeat });
+    }
+}
+/**
+ * Describes a failed shard acquisition.
+ */
+export class FailedPickUp {
+    shard;
+    error;
+    // prettier-ignore
+    /**
+     * Creates facts for a failed shard acquisition.
+     *
+     * @param shard The shard whose acquisition failed.
+     * @param error The acquisition failure.
+     */
+    constructor(shard, error) {
+        this.shard = shard;
+        this.error = error;
+    }
+    /**
+     * Returns a failed delivery result without acquiring ownership.
+     *
+     * @returns The failed-result action.
+     */
+    fail() {
+        return Object.freeze({ execute: () => Promise.resolve() });
+    }
+}
+/**
+ * Describes a shard already owned by another worker.
+ */
+export class AlreadyPickedUp {
+    shard;
+    // prettier-ignore
+    /**
+     * Creates facts for an already-owned shard.
+     *
+     * @param shard The shard already owned by another worker.
+     */
+    constructor(shard) {
+        this.shard = shard;
+    }
+    /**
+     * Returns a skipped delivery result without acquiring ownership.
+     *
+     * @returns The skipped-result action.
+     */
+    skip() {
+        return Object.freeze({ execute: () => Promise.resolve() });
+    }
+}
+/**
+ * Controls finite delivery failure actions without scheduling retries.
+ *
+ * Subclasses can return direct values or promises from every hook. The default
+ * reception policy marks the failed row delivered so independent targets keep
+ * draining; it never persists attempts, receipts, markers, or quarantine data.
+ */
+export class DeliveryMonitor {
+    // prettier-ignore
+    /**
+     * Checks whether delivery can continue after a lifecycle stage.
+     *
+     * @param stage The stage that has just been reached.
+     * @returns Whether the current finite delivery should continue.
+     */
+    shouldContinueAfter(stage) {
+        void stage;
+        return true;
+    }
+    /**
+     * Handles successful shard ownership before Inbox reads begin.
+     *
+     * @param shard The owned shard about to drain.
+     * @returns A promise that settles after the hook completes.
+     */
+    onDeliveryStarted(shard) {
+        void shard;
+    }
+    /**
+     * Handles a delivery after shard ownership has been released.
+     *
+     * @param statistics The immutable result counts for the finished delivery.
+     * @returns A promise that settles after the hook completes.
+     */
+    onDeliveryCompleted(statistics) {
+        void statistics;
+    }
+    /**
+     * Returns an action after endpoint dispatch or acknowledgement fails.
+     *
+     * @param reception The failure facts and one-shot actions.
+     * @returns The selected asynchronous reception action.
+     */
+    onReceptionFailure(reception) {
+        return reception.markDelivered();
+    }
+    /**
+     * Returns an action after shard acquisition fails.
+     *
+     * @param failure The failed acquisition facts.
+     * @returns The selected pickup action.
+     */
+    onShardPickUpFailure(failure) {
+        return failure.fail();
+    }
+    /**
+     * Returns an action when another worker already owns the shard.
+     *
+     * @param failure The already-owned shard facts.
+     * @returns The selected pickup action.
+     */
+    onShardAlreadyPicked(failure) {
+        return failure.skip();
+    }
+}
+//# sourceMappingURL=delivery-monitor.js.map

package/dist/delivery/delivery-monitor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-monitor.js","sourceRoot":"","sources":["../../src/delivery/delivery-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiCH;;GAEG;AACH,MAAM,OAAO,eAAe;IAYf;IACA;IACQ;IACA;IAdnB,kBAAkB;IAElB;;;;;;;OAOG;IACH,YACW,OAAqB,EACrB,KAAc,EACN,IAAyB,EACzB,MAA2B;QAHnC,YAAO,GAAP,OAAO,CAAc;QACrB,UAAK,GAAL,KAAK,CAAS;QACN,SAAI,GAAJ,IAAI,CAAqB;QACzB,WAAM,GAAN,MAAM,CAAqB;IAC3C,CAAC;IAEJ;;;;OAIG;IACH,aAAa;QACX,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,iBAAiB;QACf,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,YAAY;IAUZ;IACA;IAVX,kBAAkB;IAElB;;;;;OAKG;IACH,YACW,KAAiB,EACjB,KAAc;QADd,UAAK,GAAL,KAAK,CAAY;QACjB,UAAK,GAAL,KAAK,CAAS;IACtB,CAAC;IAEJ;;;;OAIG;IACH,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAe;IAQL;IAPrB,kBAAkB;IAElB;;;;OAIG;IACH,YAAqB,KAAiB;QAAjB,UAAK,GAAL,KAAK,CAAY;IAAG,CAAC;IAE1C;;;;OAIG;IACH,IAAI;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;CACF;AA6BD;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,kBAAkB;IAElB;;;;;OAKG;IACH,mBAAmB,CAAC,KAAoB;QACtC,KAAK,KAAK,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,KAAiB;QACjC,KAAK,KAAK,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,UAA8B;QAChD,KAAK,UAAU,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,SAA0B;QAC3C,OAAO,SAAS,CAAC,aAAa,EAAE,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAqB;QACxC,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACH,oBAAoB,CAAC,OAAwB;QAC3C,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/delivery/delivery-ports.d.ts

@@ -0,0 +1,141 @@
+import type { InboxMessage, InboxMessageId, InboxMessageInput, InboxReadOptions, InboxWriteResult } from "./inbox.js";
+import type { WorkerId } from "@spine-event-engine/proto/delivery";
+import type { ShardIndex } from "./shard-index.js";
+import type { ShardSession } from "./sharded-work-registry.js";
+/**
+ * Cancellation and per-call deadline propagated through delivery port work.
+ */
+export interface DeliveryOperationOptions {
+    /**
+     * Cooperative cancellation propagated through reads, mutations, lease work, and completion.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Non-negative safe-integer operation budget in milliseconds, measured from admission; zero is expired.
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Server-owned durable inbox boundary used by delivery drains.
+ */
+export interface DeliveryInbox {
+    /**
+     * Session fence kind this inbox accepts; ports supplied together must agree.
+     */
+    readonly sessionKind: DeliveryWorkSession["kind"];
+    /**
+     * Persists one incoming message before any worker observes it.
+     *
+     * @param input Describes the message to make durable.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The write or deduplication outcome.
+     */
+    receive(input: InboxMessageInput, options?: DeliveryOperationOptions): Promise<InboxWriteResult>;
+    /**
+     * Reads one bounded continuation page for a shard.
+     *
+     * @param shard Selects the shard to inspect.
+     * @param options Filters and bounds the ordered page.
+     * @returns The matching message snapshots.
+     */
+    read(shard: ShardIndex, options?: InboxReadOptions & DeliveryOperationOptions): Promise<readonly InboxMessage[]>;
+    /**
+     * Finds one exact message without claiming delivery work.
+     *
+     * @param id Identifies the durable message.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The message when it remains durable.
+     */
+    readMessage(id: InboxMessageId, options?: DeliveryOperationOptions): Promise<InboxMessage | undefined>;
+    /**
+     * Marks one exact pending Inbox row delivered.
+     *
+     * @param message Supplies the expected pending row snapshot.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The delivered row, or `undefined` when durable acknowledgement failed.
+     */
+    markDelivered(message: InboxMessage, options?: DeliveryOperationOptions): Promise<InboxMessage | undefined>;
+    /**
+     * Removes one exact delivered snapshot atomically while a direct shard
+     * session remains current.
+     *
+     * Built-in direct Inbox storage implements this through its provider-owned
+     * ownership-and-delete operation. Custom structural ports may omit this
+     * optional retention capability. RemoteInbox omits it because acknowledgement
+     * already removes its pending row.
+     *
+     * @param message Supplies the expected delivered row snapshot.
+     * @param session Supplies the currently owned shard session.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns `true` only when the exact snapshot was removed under current ownership.
+     */
+    removeDelivered?(message: InboxMessage, session: DeliveryWorkSession, options?: DeliveryOperationOptions): Promise<boolean>;
+}
+/**
+ * Server-owned exclusive shard-work boundary.
+ */
+export interface DeliveryWorkRegistry {
+    /**
+     * Session fence kind this registry issues; ports supplied together must agree.
+     */
+    readonly sessionKind: DeliveryWorkSession["kind"];
+    /**
+     * Acquires one shard work fence when it is available.
+     *
+     * @param shard Selects the shard to acquire.
+     * @param worker Identifies the complete worker acquiring the fence.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The acquired session, when the shard is available.
+     */
+    pickUp(shard: ShardIndex, worker: WorkerId, options?: DeliveryOperationOptions): Promise<DeliveryWorkSession | undefined>;
+    /**
+     * Updates a local leased session when it remains current.
+     *
+     * @param session Supplies the leased session to renew.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The renewed session, when its fence remains valid.
+     */
+    renew?(session: LeasedDeliveryWorkSession, options?: DeliveryOperationOptions): Promise<LeasedDeliveryWorkSession | undefined>;
+    /**
+     * Validates ownership immediately before a guarded side effect.
+     *
+     * Leased registries return the renewed session. Exclusive registries return
+     * the current session only while its authoritative remote fence still
+     * matches.
+     *
+     * @param session Supplies the session to validate.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns The current session, or `undefined` after ownership loss.
+     */
+    validateOwnership(session: DeliveryWorkSession, options?: DeliveryOperationOptions): Promise<DeliveryWorkSession | undefined>;
+    /**
+     * Removes a held work fence.
+     *
+     * @param session Supplies the session to release.
+     * @param options Propagates cancellation and a delivery deadline.
+     * @returns Whether the held fence was released.
+     */
+    release(session: DeliveryWorkSession, options?: DeliveryOperationOptions): Promise<boolean>;
+}
+/**
+ * Local registry session that has renewable expiry fencing.
+ */
+export type LeasedDeliveryWorkSession = ShardSession;
+/**
+ * Remote exclusive session without a fictional lease or renewal timer.
+ */
+export interface ExclusiveDeliveryWorkSession {
+    /**
+     * Identifies an exclusive remote fence without renewal.
+     */
+    readonly kind: "EXCLUSIVE";
+    /**
+     * Selects the shard held by the exclusive fence.
+     */
+    readonly shard: ShardIndex;
+}
+/**
+ * Honest session union accepted by delivery work.
+ */
+export type DeliveryWorkSession = LeasedDeliveryWorkSession | ExclusiveDeliveryWorkSession;
+//# sourceMappingURL=delivery-ports.d.ts.map

package/dist/delivery/delivery-ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-ports.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-ports.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IAGvC;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEjG;;;;;;OAMG;IACH,IAAI,CACF,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE,gBAAgB,GAAG,wBAAwB,GACpD,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;IAEpC;;;;;;OAMG;IACH,WAAW,CACT,EAAE,EAAE,cAAc,EAClB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAErC;;;;;;OAMG;IACH,aAAa,CACX,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAErC;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,CACd,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAElD;;;;;;;OAOG;IACH,MAAM,CACJ,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,QAAQ,EAChB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,KAAK,CAAC,CACJ,OAAO,EAAE,yBAAyB,EAClC,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAAC;IAElD;;;;;;;;;;OAUG;IACH,iBAAiB,CACf,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAAC;IAE5C;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,YAAY,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAG3C;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,yBAAyB,GAAG,4BAA4B,CAAC"}

package/dist/delivery/delivery-ports.js

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=delivery-ports.js.map

package/dist/delivery/delivery-ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-ports.js","sourceRoot":"","sources":["../../src/delivery/delivery-ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/delivery/delivery-run-control.d.ts

@@ -0,0 +1,50 @@
+import { type Delivery, type DeliveryResult, type DeliveryRunOptions } from "./delivery-builder.js";
+import type { ShardIndex } from "./shard-index.js";
+import type { InboxMessage } from "./inbox.js";
+/**
+ * Controls admission for one finite delivery run.
+ */
+export declare class DeliveryRunControl {
+    #private;
+    /**
+     * Creates controlled admission for a builder-created delivery.
+     *
+     * @param delivery The builder-created delivery to control.
+     */
+    constructor(delivery: Delivery);
+    /**
+     * Executes one controlled delivery until it settles or its signal aborts.
+     *
+     * @param options The finite shard run and its cancellation signal.
+     * @returns The delivery result, or an abort error.
+     */
+    run(options: DeliveryControlledRun): Promise<DeliveryResult>;
+}
+/**
+ * Describes one controlled finite delivery request.
+ */
+export interface DeliveryControlledRun extends DeliveryRunOptions {
+    /**
+     * Identifies the shard to drain.
+     */
+    readonly shard: ShardIndex;
+    /**
+     * Cancels the controlled run.
+     */
+    readonly signal: AbortSignal;
+    /**
+     * Determines whether the private controlled run owns a pending row before dispatch or acknowledgment.
+     *
+     * @param message Contains the pending Inbox row.
+     * @returns `true` if this controlled run owns the row.
+     * @internal
+     */
+    readonly acceptMessage?: (message: InboxMessage) => boolean;
+    /**
+     * Completes private admission cleanup when the controlled run settles before dispatch.
+     *
+     * @internal
+     */
+    readonly onRunSettled?: () => void;
+}
+//# sourceMappingURL=delivery-run-control.d.ts.map

package/dist/delivery/delivery-run-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-run-control.d.ts","sourceRoot":"","sources":["../../src/delivery/delivery-run-control.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,qBAAa,kBAAkB;;IAG7B;;;;OAIG;gBACS,QAAQ,EAAE,QAAQ;IAQ9B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;CA6B7D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAG/D;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC;IAE5D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC"}

package/dist/delivery/delivery-run-control.js

@@ -0,0 +1,66 @@
+/*
+ * 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 { deliveryControls, } from "./delivery-builder.js";
+/**
+ * Controls admission for one finite delivery run.
+ */
+export class DeliveryRunControl {
+    #runControlled;
+    /**
+     * Creates controlled admission for a builder-created delivery.
+     *
+     * @param delivery The builder-created delivery to control.
+     */
+    constructor(delivery) {
+        const runControlled = deliveryControls.runner(delivery);
+        if (runControlled === undefined) {
+            throw new TypeError("DeliverySupervisor requires a Delivery built by DeliveryBuilder.");
+        }
+        this.#runControlled = runControlled;
+    }
+    /**
+     * Executes one controlled delivery until it settles or its signal aborts.
+     *
+     * @param options The finite shard run and its cancellation signal.
+     * @returns The delivery result, or an abort error.
+     */
+    run(options) {
+        if (options.signal.aborted)
+            return Promise.reject(this.#abortError(options.signal));
+        const settled = this.#runControlled(options);
+        let aborted;
+        const abort = () => {
+            aborted = this.#abortError(options.signal);
+        };
+        options.signal.addEventListener("abort", abort, { once: true });
+        // spine-log-boundary: server.delivery_control_settlement_observer
+        void settled.catch(() => undefined);
+        return settled
+            .then((result) => {
+            if (aborted !== undefined)
+                throw aborted;
+            return result;
+        }, (error) => {
+            throw error;
+        })
+            .finally(() => {
+            options.signal.removeEventListener("abort", abort);
+            options.onRunSettled?.();
+        });
+    }
+    #abortError(signal) {
+        return signal.reason instanceof Error ? signal.reason : new Error("Delivery run was aborted.");
+    }
+}
+//# sourceMappingURL=delivery-run-control.js.map

package/dist/delivery/delivery-run-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-run-control.js","sourceRoot":"","sources":["../../src/delivery/delivery-run-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,uBAAuB,CAAC;AAI/B;;GAEG;AACH,MAAM,OAAO,kBAAkB;IACpB,cAAc,CAA8D;IAErF;;;;OAIG;IACH,YAAY,QAAkB;QAC5B,MAAM,aAAa,GAAG,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,SAAS,CAAC,kEAAkE,CAAC,CAAC;QAC1F,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACH,GAAG,CAAC,OAA8B;QAChC,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QACpF,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,OAA0B,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,kEAAkE;QAClE,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACpC,OAAO,OAAO;aACX,IAAI,CACH,CAAC,MAAM,EAAE,EAAE;YACT,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,OAAO,CAAC;YACzC,OAAO,MAAM,CAAC;QAChB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,MAAM,KAAK,CAAC;QACd,CAAC,CACF;aACA,OAAO,CAAC,GAAG,EAAE;YACZ,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACnD,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;QAC3B,CAAC,CAAC,CAAC;IACP,CAAC;IAED,WAAW,CAAC,MAAmB;QAC7B,OAAO,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACjG,CAAC;CACF"}