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

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

@@ -0,0 +1,218 @@
+import type { DeliveryReady } from "../context/local-inbox-handoff.js";
+import type { DeliveryLoopProgress } from "./delivery-loop.js";
+import { type DeliveryWorker, type DeliveryWorkerEvidence, type DeliveryWorkerObligation } from "./delivery-worker.js";
+import { ShardIndex } from "./shard-index.js";
+/**
+ * Serializes finite worker starts for one delivery generation.
+ */
+export declare class DeliveryRunCoordinator {
+    #private;
+    /**
+     * Creates a coordinator for configured generation scopes.
+     *
+     * @param options The scopes, worker seam, and optional settlement observer.
+     */
+    constructor(options: {
+        readonly scopes: readonly DeliveryRunScope[];
+        readonly worker: DeliveryRunWorker;
+        readonly onSettlement?: (settlement: DeliveryScopeSettlement) => unknown;
+    });
+    /**
+     * Updates this live generation with later registered delivery scopes.
+     *
+     * @param scopes The delivery scopes to configure.
+     */
+    configure(scopes: readonly DeliveryRunScope[]): void;
+    /**
+     * Returns whether the coordinator has finalized safely for replacement.
+     *
+     * @returns Whether replacement is safe.
+     */
+    get replacementSafe(): boolean;
+    /**
+     * Returns whether the coordinator has finalized retirement.
+     *
+     * @returns Whether retirement is complete.
+     */
+    get retired(): boolean;
+    /**
+     * Returns the current generation-local delivery scope count.
+     *
+     * @returns The configured scope count.
+     */
+    get configuredScopeCount(): number;
+    /**
+     * Starts the configured scopes and resolves their latest settlement.
+     *
+     * @param scopes The scopes to admit.
+     * @returns The resulting settlement.
+     */
+    start(scopes: readonly DeliveryRunScope[]): Promise<DeliveryRunSettlement>;
+    /**
+     * Notifies the coordinator that one configured scope is ready.
+     *
+     * @param scope The ready scope.
+     */
+    notify(scope: DeliveryRunScope): void;
+    /**
+     * Removes quiesced, permanently retired owner state without disturbing siblings.
+     *
+     * @param ownerKeys The owner keys to remove.
+     * @returns A promise that resolves after the selected owner state is removed.
+     */
+    removeOwners(ownerKeys: readonly string[]): Promise<void>;
+    /**
+     * Awaits retained work that could still start selected owners without reclaiming evidence.
+     *
+     * @param ownerKeys The owner keys whose work must settle.
+     * @returns A promise that resolves after selected owners cannot start retained work.
+     */
+    awaitOwnersBarrier(ownerKeys: readonly string[]): Promise<void>;
+    /**
+     * Returns immutable evidence for configured and pending scopes.
+     *
+     * @returns The current generation settlement.
+     */
+    settlement(): DeliveryRunSettlement;
+    /**
+     * Closes this coordinator after reporting its terminal settlement.
+     *
+     * @param onReport The terminal settlement reporter.
+     * @returns A promise that settles after retirement and terminal reporting complete.
+     */
+    retire(onReport: (settlement: DeliveryRunSettlement) => Promise<void>): Promise<void>;
+    /**
+     * Returns causes only from this coordinator's exact current retirement failure.
+     *
+     * @param reason The observed retirement reason.
+     * @returns The matching causes, when present.
+     */
+    takeRetirementFailureCauses(reason: unknown): readonly unknown[] | undefined;
+}
+/**
+ * Identifies one generation-local runtime owner.
+ */
+export interface DeliveryRunOwner {
+    /**
+     * Holds the stable owner key.
+     */
+    readonly key: string;
+}
+/**
+ * Describes owner-qualified readiness admitted for one generation.
+ */
+export interface DeliveryRunScope {
+    /**
+     * Identifies the scope owner.
+     */
+    readonly owner: DeliveryRunOwner;
+    /**
+     * Holds the canonical readiness facts.
+     */
+    readonly ready: DeliveryReady;
+}
+/**
+ * Describes a finite worker obligation for one delivery-scope union.
+ */
+export interface DeliveryRunObligation extends DeliveryWorkerObligation {
+    /**
+     * Lists the admitted delivery scopes.
+     */
+    readonly scopes: readonly DeliveryRunScope[];
+}
+/**
+ * Defines the generation worker seam used by the bounded run coordinator.
+ */
+export interface DeliveryRunWorker {
+    /**
+     * Starts the requested shards for one obligation.
+     *
+     * @param obligation The generation obligation.
+     * @param shards The shards to start.
+     * @returns The worker evidence.
+     */
+    start(obligation: DeliveryRunObligation, shards: readonly ShardIndex[]): Promise<DeliveryWorkerEvidence>;
+    /**
+     * Stops loop admission irreversibly.
+     */
+    stop(): void;
+    /**
+     * Awaits active work without interrupting it.
+     *
+     * @returns A promise that resolves after active work settles.
+     */
+    awaitSettled(): Promise<void>;
+    /**
+     * Closes after a completed stop and proven settlement. Permanently closes every
+     * worker start entry before settling, even when inert-resource cleanup fails.
+     *
+     * @returns A promise that settles after the worker retires.
+     */
+    retire(): Promise<void>;
+}
+/**
+ * Describes the latest bounded disposition for one configured delivery scope.
+ */
+export interface DeliveryScopeSettlement {
+    /**
+     * Holds the configured scope.
+     */
+    readonly scope: DeliveryRunScope;
+    /**
+     * Names the latest scope disposition.
+     */
+    readonly disposition: "IDLE" | "PARKED" | "REJECTED" | "STOPPED";
+    /**
+     * Holds the rejection cause, when present.
+     */
+    readonly cause?: unknown;
+    /**
+     * Holds the last safe loop progress, when present.
+     */
+    readonly progress?: DeliveryLoopProgress;
+}
+/**
+ * Describes bounded generation evidence retained by the coordinator.
+ */
+export interface DeliveryRunSettlement {
+    /**
+     * Lists settled configured scopes.
+     */
+    readonly scopes: readonly DeliveryScopeSettlement[];
+    /**
+     * Lists scopes still pending admission.
+     */
+    readonly pending: readonly DeliveryRunScope[];
+}
+/**
+ * Reports retirement that failed before quiescence.
+ */
+export declare class DeliveryRunQuiescenceError extends Error {
+    /**
+     * Holds the failure that prevented quiescence.
+     */
+    readonly cause: unknown;
+    /**
+     * Creates a quiescence error.
+     *
+     * @param cause The failure that prevented quiescence.
+     */
+    constructor(cause: unknown);
+}
+/**
+ * Adapts workers for package-owned delivery generations.
+ */
+export interface DeliveryRunWorkers {
+    /**
+     * Creates a generation coordinator seam for one worker.
+     *
+     * @param worker The worker to adapt.
+     * @returns The generation worker seam.
+     */
+    worker(worker: DeliveryWorker): DeliveryRunWorker;
+}
+/**
+ * Adapts workers for package-owned delivery generations.
+ */
+export declare const deliveryRunWorkers: DeliveryRunWorkers;
+//# sourceMappingURL=delivery-run-coordinator.d.ts.map

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

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