@memberjunction/work-queue-core 0.0.0 → 6.2.0-edge.3

package/dist/operator.d.ts

@@ -0,0 +1,60 @@
+import type { WorkMessage } from './envelope.js';
+import type { SubscriptionBinding } from './transport.js';
+export interface SubscriptionStats {
+    SubscriptionName: string;
+    Pending: number;
+    InFlight: number;
+    DeadLettered: number;
+    /** null when not applicable/unsupported */
+    BlockedKeys: number | null;
+    /** AWS: always null in Phase 1 (no CloudWatch client; use the CloudWatch alarm) */
+    OldestPendingAgeSeconds: number | null;
+    /** null unless CompletedCounts */
+    CompletedLastHour: number | null;
+    AsOf: string;
+}
+export interface DeadLetterRecord {
+    /** Database: Delivery.ID; AWS: envelope MessageID */
+    DeliveryID: string;
+    Message: WorkMessage;
+    PartitionKey: string | null;
+    Attempts: number;
+    /** handler reason, 'MaxAttemptsExceeded', 'LeaseExpired', 'HandlerNotRegistered', 'RedrivePolicy', 'InvalidEnvelope', … */
+    Reason: string;
+    LastError: string | null;
+    DeadLetteredAt: string | null;
+    /** Ordered head on the Database transport */
+    BlocksKey: boolean;
+}
+/** Derived from the delivery rows; nothing about a partition is stored elsewhere (spec 03 §7). */
+export type PartitionCondition = 'Idle' | 'InFlight' | 'Blocked';
+export interface PartitionStateRecord {
+    PartitionKey: string;
+    Condition: PartitionCondition;
+    HeadDeliveryID: string | null;
+    WaitingItems: number;
+}
+export interface Page<T> {
+    Items: T[];
+    NextCursor: string | null;
+}
+export type OperatorResult = {
+    Supported: false;
+}
+/** CancelRequested: present (true) only when an InFlight delivery was asked to stop (spec 03 §7). */
+ | {
+    Supported: true;
+    Changed: boolean;
+    CancelRequested?: boolean;
+};
+export interface ITransportOperator {
+    GetStats(subscription: SubscriptionBinding): Promise<SubscriptionStats>;
+    ListDeadLetters(subscription: SubscriptionBinding, cursor: string | null, pageSize: number): Promise<Page<DeadLetterRecord> | null>;
+    /** condition null = all non-Idle keys. Returns null when !ListPartitions. */
+    ListPartitions(subscription: SubscriptionBinding, condition: PartitionCondition | null, cursor: string | null, pageSize: number): Promise<Page<PartitionStateRecord> | null>;
+    Replay(subscription: SubscriptionBinding, deliveryID: string, actorUserID: string | null, note: string | null): Promise<OperatorResult>;
+    /** Pending (requires CancelPending) or DeadLettered → Discarded immediately.
+     *  InFlight (requires CancelInFlight) → CancelRequestedAt set, `CancelRequested: true` (spec 03 §7). */
+    Discard(subscription: SubscriptionBinding, deliveryID: string, reason: string, actorUserID: string | null): Promise<OperatorResult>;
+}
+//# sourceMappingURL=operator.d.ts.map

package/dist/operator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../src/operator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mFAAmF;IACnF,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC7B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,2HAA2H;IAC3H,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,kGAAkG;AAClG,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,IAAI,CAAC,CAAC;IACnB,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,MAAM,cAAc,GACpB;IAAE,SAAS,EAAE,KAAK,CAAA;CAAE;AACtB,qGAAqG;GACnG;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,YAAY,EAAE,mBAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxE,eAAe,CAAC,YAAY,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,CAAC;IACpI,6EAA6E;IAC7E,cAAc,CACV,YAAY,EAAE,mBAAmB,EACjC,SAAS,EAAE,kBAAkB,GAAG,IAAI,EACpC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACxI;4GACwG;IACxG,OAAO,CAAC,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACvI"}

package/dist/operator.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=operator.js.map

package/dist/operator.js.map

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

package/dist/policy.d.ts

@@ -0,0 +1,24 @@
+/** `Ordered` is supported by the Database transport only (spec 03 §3.1). */
+export type PartitionMode = 'None' | 'Exclusive' | 'Ordered';
+export type HeartbeatMode = 'Auto' | 'Manual';
+export type HostType = 'MJWorker' | 'External';
+export type DeliveryStatus = 'Pending' | 'InFlight' | 'Completed' | 'DeadLettered' | 'Discarded';
+export interface SubscriptionPolicy {
+    SubscriptionName: string;
+    TopicName: string;
+    PartitionMode: PartitionMode;
+    /** default 5 */
+    MaxAttempts: number;
+    /** default 10 */
+    BackoffBaseSeconds: number;
+    /** default 900 */
+    BackoffMaxSeconds: number;
+    /** default 60 */
+    LeaseSeconds: number;
+    /** default 'Auto' */
+    HeartbeatMode: HeartbeatMode;
+    MaxProcessingSeconds?: number;
+}
+/** Column defaults from spec 03 §6.3, for callers that build policies outside the database. */
+export declare const SUBSCRIPTION_POLICY_DEFAULTS: Readonly<Pick<SubscriptionPolicy, 'PartitionMode' | 'MaxAttempts' | 'BackoffBaseSeconds' | 'BackoffMaxSeconds' | 'LeaseSeconds' | 'HeartbeatMode'>>;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAC9C,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;AAC/C,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,GAAG,WAAW,CAAC;AAEjG,MAAM,WAAW,kBAAkB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,aAAa,CAAC;IAC7B,gBAAgB;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,aAAa,EAAE,aAAa,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+FAA+F;AAC/F,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAC/C,IAAI,CAAC,kBAAkB,EAAE,eAAe,GAAG,aAAa,GAAG,oBAAoB,GAAG,mBAAmB,GAAG,cAAc,GAAG,eAAe,CAAC,CAQ5I,CAAC"}

package/dist/policy.js

@@ -0,0 +1,10 @@
+/** Column defaults from spec 03 §6.3, for callers that build policies outside the database. */
+export const SUBSCRIPTION_POLICY_DEFAULTS = {
+    PartitionMode: 'None',
+    MaxAttempts: 5,
+    BackoffBaseSeconds: 10,
+    BackoffMaxSeconds: 900,
+    LeaseSeconds: 60,
+    HeartbeatMode: 'Auto',
+};
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAuBA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,4BAA4B,GAErC;IACA,aAAa,EAAE,MAAM;IACrB,WAAW,EAAE,CAAC;IACd,kBAAkB,EAAE,EAAE;IACtB,iBAAiB,EAAE,GAAG;IACtB,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE,MAAM;CACxB,CAAC"}

package/dist/publishing.d.ts

@@ -0,0 +1,58 @@
+import type { WorkJson, WorkPayloadRef } from './envelope.js';
+export interface PublishRequest<TPayload extends WorkJson = WorkJson> {
+    MessageID?: string;
+    PartitionKey?: string;
+    Attributes?: Record<string, string>;
+    Payload?: TPayload;
+    PayloadRef?: WorkPayloadRef;
+    CorrelationID?: string;
+    /** Suppresses a second publish with the same key to the same topic inside the TTL window. */
+    DeduplicationKey?: string;
+    /** Default: topic DefaultDeduplicationTTLSeconds. */
+    DeduplicationTTLSeconds?: number;
+}
+export type PublishStatus = 'Accepted' | 'Duplicate' | 'Rejected';
+export interface PublishError {
+    Code: string;
+    Message: string;
+    Retryable: boolean;
+}
+export interface PublishResult {
+    /** For Duplicate: the MessageID of the publish that owns the key (or the existing MessageID). */
+    MessageID: string;
+    Status: PublishStatus;
+    Error?: PublishError;
+}
+export interface IWorkPublisher {
+    /** Batch publish. Results are positionally aligned with requests. Partial success is possible. */
+    Publish<TPayload extends WorkJson>(topic: string, requests: PublishRequest<TPayload>[]): Promise<PublishResult[]>;
+}
+/**
+ * Every publish error code used anywhere in the work queue (spec 03 §1.1). Core produces the
+ * envelope codes; the engine, drivers, REST extension and API client produce the rest.
+ */
+export declare const PublishErrorCodes: {
+    readonly PayloadTooLarge: "PayloadTooLarge";
+    readonly InvalidAttributes: "InvalidAttributes";
+    readonly InvalidPayload: "InvalidPayload";
+    readonly InvalidPartitionKey: "InvalidPartitionKey";
+    readonly InvalidMessageID: "InvalidMessageID";
+    readonly InvalidDeduplication: "InvalidDeduplication";
+    readonly TopicNotFound: "TopicNotFound";
+    readonly TopicDisabled: "TopicDisabled";
+    readonly TopicNotExternallyPublishable: "TopicNotExternallyPublishable";
+    readonly Forbidden: "Forbidden";
+    readonly TopicUnbound: "TopicUnbound";
+    readonly MessageIDConflict: "MessageIDConflict";
+    readonly DeduplicationPending: "DeduplicationPending";
+    readonly TransportUnavailable: "TransportUnavailable";
+    readonly TransportRejected: "TransportRejected";
+    readonly BadRequest: "BadRequest";
+    readonly Unauthorized: "Unauthorized";
+    readonly InvalidResponse: "InvalidResponse";
+};
+export type PublishErrorCode = (typeof PublishErrorCodes)[keyof typeof PublishErrorCodes];
+export declare function IsRetryablePublishErrorCode(code: string): boolean;
+export declare function CreatePublishError(code: string, message: string): PublishError;
+export declare function RejectedPublishResult(messageID: string, code: string, message: string): PublishResult;
+//# sourceMappingURL=publishing.d.ts.map

package/dist/publishing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing.d.ts","sourceRoot":"","sources":["../src/publishing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAElE,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC1B,iGAAiG;IACjG,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B,kGAAkG;IAClG,OAAO,CAAC,QAAQ,SAAS,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CACrH;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;CAmBpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAS1F,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAE9E;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAErG"}

package/dist/publishing.js

@@ -0,0 +1,40 @@
+/**
+ * Every publish error code used anywhere in the work queue (spec 03 §1.1). Core produces the
+ * envelope codes; the engine, drivers, REST extension and API client produce the rest.
+ */
+export const PublishErrorCodes = {
+    PayloadTooLarge: 'PayloadTooLarge',
+    InvalidAttributes: 'InvalidAttributes',
+    InvalidPayload: 'InvalidPayload',
+    InvalidPartitionKey: 'InvalidPartitionKey',
+    InvalidMessageID: 'InvalidMessageID',
+    InvalidDeduplication: 'InvalidDeduplication',
+    TopicNotFound: 'TopicNotFound',
+    TopicDisabled: 'TopicDisabled',
+    TopicNotExternallyPublishable: 'TopicNotExternallyPublishable',
+    Forbidden: 'Forbidden',
+    TopicUnbound: 'TopicUnbound',
+    MessageIDConflict: 'MessageIDConflict',
+    DeduplicationPending: 'DeduplicationPending',
+    TransportUnavailable: 'TransportUnavailable',
+    TransportRejected: 'TransportRejected',
+    BadRequest: 'BadRequest',
+    Unauthorized: 'Unauthorized',
+    InvalidResponse: 'InvalidResponse',
+};
+const RETRYABLE_PUBLISH_ERROR_CODES = new Set([
+    PublishErrorCodes.TopicUnbound,
+    PublishErrorCodes.DeduplicationPending,
+    PublishErrorCodes.TransportUnavailable,
+    PublishErrorCodes.InvalidResponse,
+]);
+export function IsRetryablePublishErrorCode(code) {
+    return RETRYABLE_PUBLISH_ERROR_CODES.has(code);
+}
+export function CreatePublishError(code, message) {
+    return { Code: code, Message: message, Retryable: IsRetryablePublishErrorCode(code) };
+}
+export function RejectedPublishResult(messageID, code, message) {
+    return { MessageID: messageID, Status: 'Rejected', Error: CreatePublishError(code, message) };
+}
+//# sourceMappingURL=publishing.js.map

package/dist/publishing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishing.js","sourceRoot":"","sources":["../src/publishing.ts"],"names":[],"mappings":"AAmCA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC7B,eAAe,EAAE,iBAAiB;IAClC,iBAAiB,EAAE,mBAAmB;IACtC,cAAc,EAAE,gBAAgB;IAChC,mBAAmB,EAAE,qBAAqB;IAC1C,gBAAgB,EAAE,kBAAkB;IACpC,oBAAoB,EAAE,sBAAsB;IAC5C,aAAa,EAAE,eAAe;IAC9B,aAAa,EAAE,eAAe;IAC9B,6BAA6B,EAAE,+BAA+B;IAC9D,SAAS,EAAE,WAAW;IACtB,YAAY,EAAE,cAAc;IAC5B,iBAAiB,EAAE,mBAAmB;IACtC,oBAAoB,EAAE,sBAAsB;IAC5C,oBAAoB,EAAE,sBAAsB;IAC5C,iBAAiB,EAAE,mBAAmB;IACtC,UAAU,EAAE,YAAY;IACxB,YAAY,EAAE,cAAc;IAC5B,eAAe,EAAE,iBAAiB;CAC5B,CAAC;AAIX,MAAM,6BAA6B,GAAwB,IAAI,GAAG,CAAS;IACvE,iBAAiB,CAAC,YAAY;IAC9B,iBAAiB,CAAC,oBAAoB;IACtC,iBAAiB,CAAC,oBAAoB;IACtC,iBAAiB,CAAC,eAAe;CACpC,CAAC,CAAC;AAEH,MAAM,UAAU,2BAA2B,CAAC,IAAY;IACpD,OAAO,6BAA6B,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAe;IAC5D,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,IAAY,EAAE,OAAe;IAClF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,kBAAkB,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;AAClG,CAAC"}

package/dist/runtime/ConsumerRuntime.d.ts

@@ -0,0 +1,46 @@
+import type { WorkJson } from '../envelope.js';
+import type { WorkHandler, WorkLogger } from '../handler.js';
+import type { SubscriptionPolicy } from '../policy.js';
+import type { ITransportConsumer, ReceivedDelivery, SettleResult } from '../transport.js';
+import type { ConsumerRuntimeOptions } from './types.js';
+/** Transport-agnostic loop: receive → run handler with lease management → settle. */
+export declare class ConsumerRuntime<TPayload extends WorkJson = WorkJson> {
+    private readonly consumer;
+    private readonly handlerFactory;
+    private readonly policy;
+    private readonly options;
+    private readonly log;
+    private readonly now;
+    private running;
+    private loopPromise;
+    /** Keyed by DeliveryExecution.ExecutionKey (DeliveryID + LeaseToken), never by DeliveryID alone. */
+    private readonly executions;
+    private receiveController;
+    private wakeResolver;
+    private wakeTimer;
+    private kickPending;
+    constructor(consumer: ITransportConsumer<TPayload>, handlerFactory: () => WorkHandler<TPayload>, policy: SubscriptionPolicy, options: ConsumerRuntimeOptions, log: WorkLogger, now?: () => number);
+    get InFlightCount(): number;
+    get IsRunning(): boolean;
+    Start(): void;
+    /** Wake an idle loop immediately (used after in-process publish). */
+    Kick(): void;
+    /** Stops receiving, waits up to ShutdownDrainMs, then aborts remaining handlers and releases their deliveries. */
+    Stop(): Promise<void>;
+    /** Process exactly the given deliveries (Lambda mode: no loop). Results align with the input. */
+    ProcessBatch(deliveries: ReceivedDelivery<TPayload>[]): Promise<SettleResult[]>;
+    private loop;
+    private receive;
+    private releaseUnstarted;
+    private startExecution;
+    private reportSettle;
+    private waitForExecutions;
+    /** Resolves true when `work` finishes within `timeoutMs`, false otherwise. Never rejects on timeout. */
+    private within;
+    private groupIntoLanes;
+    private runLane;
+    private releaseSkipped;
+    private sleep;
+    private wake;
+}
+//# sourceMappingURL=ConsumerRuntime.d.ts.map

package/dist/runtime/ConsumerRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsumerRuntime.d.ts","sourceRoot":"","sources":["../../src/runtime/ConsumerRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAOtD,qFAAqF;AACrF,qBAAa,eAAe,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ;IAWzD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAfxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAA8B;IACjD,oGAAoG;IACpG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiD;IAC5E,OAAO,CAAC,iBAAiB,CAAyB;IAClD,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,WAAW,CAAS;gBAGP,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACtC,cAAc,EAAE,MAAM,WAAW,CAAC,QAAQ,CAAC,EAC3C,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,sBAAsB,EAC/B,GAAG,EAAE,UAAU,EACf,GAAG,GAAE,MAAM,MAAyB;IAGzD,IAAW,aAAa,IAAI,MAAM,CAEjC;IAED,IAAW,SAAS,IAAI,OAAO,CAE9B;IAEM,KAAK,IAAI,IAAI;IAgBpB,qEAAqE;IAC9D,IAAI,IAAI,IAAI;IAKnB,kHAAkH;IACrG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BlC,iGAAiG;IACpF,YAAY,CAAC,UAAU,EAAE,gBAAgB,CAAC,QAAQ,CAAC,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAgB9E,IAAI;YA8BJ,OAAO;YAcP,gBAAgB;IAc9B,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,YAAY;YAUN,iBAAiB;IAQ/B,wGAAwG;YAC1F,MAAM;IAcpB,OAAO,CAAC,cAAc;YAWR,OAAO;YAeP,cAAc;IAQ5B,OAAO,CAAC,KAAK;IAOb,OAAO,CAAC,IAAI;CAWf"}

package/dist/runtime/ConsumerRuntime.js

@@ -0,0 +1,252 @@
+import { DeliveryExecution } from './DeliveryExecution.js';
+import { ErrorMessageOf } from './outcomes.js';
+/** Transport-agnostic loop: receive → run handler with lease management → settle. */
+export class ConsumerRuntime {
+    constructor(consumer, handlerFactory, policy, options, log, now = () => Date.now()) {
+        this.consumer = consumer;
+        this.handlerFactory = handlerFactory;
+        this.policy = policy;
+        this.options = options;
+        this.log = log;
+        this.now = now;
+        this.running = false;
+        this.loopPromise = null;
+        /** Keyed by DeliveryExecution.ExecutionKey (DeliveryID + LeaseToken), never by DeliveryID alone. */
+        this.executions = new Map();
+        this.receiveController = new AbortController();
+        this.wakeResolver = null;
+        this.wakeTimer = null;
+        this.kickPending = false;
+    }
+    get InFlightCount() {
+        return this.executions.size;
+    }
+    get IsRunning() {
+        return this.running;
+    }
+    Start() {
+        if (this.running) {
+            return;
+        }
+        this.running = true;
+        this.receiveController = new AbortController();
+        this.loopPromise = this.loop().catch((error) => {
+            // The loop catches everything it awaits; this is the backstop for a throwing logger or similar.
+            this.running = false;
+            this.log.Error('Consumer loop stopped unexpectedly', error instanceof Error ? error : undefined, {
+                Subscription: this.policy.SubscriptionName,
+                Error: ErrorMessageOf(error),
+            });
+        });
+    }
+    /** Wake an idle loop immediately (used after in-process publish). */
+    Kick() {
+        this.kickPending = true;
+        this.wake();
+    }
+    /** Stops receiving, waits up to ShutdownDrainMs, then aborts remaining handlers and releases their deliveries. */
+    async Stop() {
+        this.running = false;
+        this.receiveController.abort();
+        this.wake();
+        if (this.loopPromise !== null) {
+            const loopEnded = await this.within(this.loopPromise.then(() => true), this.options.ShutdownDrainMs);
+            if (!loopEnded) {
+                this.log.Warn('Receive did not return after the abort signal; shutting down without it', {
+                    Subscription: this.policy.SubscriptionName,
+                });
+            }
+            this.loopPromise = null;
+        }
+        if (await this.waitForExecutions(this.options.ShutdownDrainMs)) {
+            return;
+        }
+        for (const running of this.executions.values()) {
+            running.Execution.Abort('Shutdown');
+        }
+        if (!(await this.waitForExecutions(this.options.ShutdownDrainMs))) {
+            this.log.Warn('Handlers still running after shutdown; their leases will expire and the deliveries will be redelivered', {
+                Subscription: this.policy.SubscriptionName,
+                Remaining: this.executions.size,
+            });
+        }
+    }
+    /** Process exactly the given deliveries (Lambda mode: no loop). Results align with the input. */
+    async ProcessBatch(deliveries) {
+        const results = [];
+        const lanes = [...this.groupIntoLanes(deliveries).values()];
+        let nextLane = 0;
+        const workerCount = Math.max(1, Math.min(this.options.Concurrency, lanes.length));
+        const workers = Array.from({ length: workerCount }, async () => {
+            while (nextLane < lanes.length) {
+                const lane = lanes[nextLane];
+                nextLane += 1;
+                await this.runLane(lane, deliveries, results);
+            }
+        });
+        await Promise.all(workers);
+        return results;
+    }
+    async loop() {
+        let idleMs = this.options.IdlePollMinMs;
+        while (this.running) {
+            const free = this.options.Concurrency - this.executions.size;
+            if (free <= 0) {
+                await this.sleep(this.options.IdlePollMaxMs);
+                continue;
+            }
+            this.kickPending = false;
+            const deliveries = await this.receive(Math.min(free, this.options.ReceiveBatchSize));
+            if (!this.running) {
+                await this.releaseUnstarted(deliveries);
+                return;
+            }
+            if (deliveries.length > 0) {
+                idleMs = this.options.IdlePollMinMs;
+                deliveries.forEach((delivery) => {
+                    void this.startExecution(delivery);
+                });
+                continue;
+            }
+            if (this.kickPending) {
+                idleMs = this.options.IdlePollMinMs;
+                continue;
+            }
+            await this.sleep(idleMs);
+            idleMs = this.kickPending ? this.options.IdlePollMinMs : Math.min(idleMs * 2, this.options.IdlePollMaxMs);
+        }
+    }
+    async receive(max) {
+        try {
+            return await this.consumer.Receive(max, this.options.ReceiveWaitSeconds ?? 0, this.receiveController.signal);
+        }
+        catch (error) {
+            if (this.running) {
+                this.log.Error('Receive failed; backing off', error instanceof Error ? error : undefined, {
+                    Subscription: this.policy.SubscriptionName,
+                    Error: ErrorMessageOf(error),
+                });
+            }
+            return [];
+        }
+    }
+    async releaseUnstarted(deliveries) {
+        for (const delivery of deliveries) {
+            try {
+                await this.consumer.Release(delivery);
+            }
+            catch (error) {
+                this.log.Warn('Release of an unstarted delivery failed; its lease will expire', {
+                    Subscription: this.policy.SubscriptionName,
+                    DeliveryID: delivery.DeliveryID,
+                    Error: ErrorMessageOf(error),
+                });
+            }
+        }
+    }
+    startExecution(delivery) {
+        const execution = new DeliveryExecution({
+            Delivery: delivery,
+            Consumer: this.consumer,
+            HandlerFactory: this.handlerFactory,
+            Policy: this.policy,
+            Log: this.log,
+            Now: this.now,
+            LeaseExpiryGraceMs: this.options.LeaseExpiryGraceMs,
+            CancelDrainMs: this.options.ShutdownDrainMs,
+        });
+        const key = execution.ExecutionKey;
+        const done = execution
+            .Run()
+            .catch((error) => ({ Kind: 'Failed', DeliveryID: delivery.DeliveryID, Error: ErrorMessageOf(error) }))
+            .then((result) => {
+            this.executions.delete(key);
+            this.reportSettle(result);
+            this.wake();
+            return result;
+        });
+        this.executions.set(key, { Execution: execution, Done: done });
+        return done;
+    }
+    reportSettle(result) {
+        if (result.Kind === 'Failed') {
+            this.log.Error('Delivery settle failed', undefined, {
+                Subscription: this.policy.SubscriptionName,
+                DeliveryID: result.DeliveryID,
+                Error: result.Error,
+            });
+        }
+    }
+    async waitForExecutions(timeoutMs) {
+        if (this.executions.size === 0) {
+            return true;
+        }
+        const allDone = Promise.all([...this.executions.values()].map((running) => running.Done)).then(() => true);
+        return this.within(allDone, timeoutMs);
+    }
+    /** Resolves true when `work` finishes within `timeoutMs`, false otherwise. Never rejects on timeout. */
+    async within(work, timeoutMs) {
+        const deadline = { Timer: null };
+        const timedOut = new Promise((resolve) => {
+            deadline.Timer = setTimeout(() => resolve(false), timeoutMs);
+        });
+        try {
+            return await Promise.race([work, timedOut]);
+        }
+        finally {
+            if (deadline.Timer !== null) {
+                clearTimeout(deadline.Timer);
+            }
+        }
+    }
+    groupIntoLanes(deliveries) {
+        const lanes = new Map();
+        const partitioned = this.policy.PartitionMode !== 'None';
+        deliveries.forEach((delivery, index) => {
+            const key = delivery.Message.PartitionKey;
+            const laneKey = partitioned && key !== undefined ? `key:${key}` : `item:${index}`;
+            lanes.set(laneKey, [...(lanes.get(laneKey) ?? []), index]);
+        });
+        return lanes;
+    }
+    async runLane(indices, deliveries, results) {
+        let blocked = false;
+        for (const index of indices) {
+            const delivery = deliveries[index];
+            if (blocked) {
+                // Spec 03 §3.2: later items of the key are released unrun, so an SQS FIFO group keeps its order.
+                results[index] = await this.releaseSkipped(delivery);
+                continue;
+            }
+            const result = await this.startExecution(delivery);
+            results[index] = result;
+            blocked = !(result.Kind === 'Settled' && result.Status === 'Completed');
+        }
+    }
+    async releaseSkipped(delivery) {
+        try {
+            return await this.consumer.Release(delivery);
+        }
+        catch (error) {
+            return { Kind: 'Failed', DeliveryID: delivery.DeliveryID, Error: ErrorMessageOf(error) };
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            this.wakeResolver = resolve;
+            this.wakeTimer = setTimeout(() => this.wake(), ms);
+        });
+    }
+    wake() {
+        if (this.wakeTimer !== null) {
+            clearTimeout(this.wakeTimer);
+            this.wakeTimer = null;
+        }
+        const resolve = this.wakeResolver;
+        this.wakeResolver = null;
+        if (resolve !== null) {
+            resolve();
+        }
+    }
+}
+//# sourceMappingURL=ConsumerRuntime.js.map

package/dist/runtime/ConsumerRuntime.js.map

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

package/dist/runtime/DeliveryExecution.d.ts

@@ -0,0 +1,83 @@
+import type { WorkJson } from '../envelope.js';
+import type { WorkAbortReason, WorkHandler, WorkLogger } from '../handler.js';
+import type { SubscriptionPolicy } from '../policy.js';
+import type { ITransportConsumer, ReceivedDelivery, SettleResult } from '../transport.js';
+export declare const MIN_AUTO_HEARTBEAT_INTERVAL_MS = 1000;
+/** Clock-skew allowance added to the lease horizon before the run is abandoned (spec 03 §3.2). */
+export declare const LEASE_EXPIRY_GRACE_MS = 5000;
+/** How long a cancelled handler gets to stop before its cancel is acknowledged anyway. */
+export declare const DEFAULT_CANCEL_DRAIN_MS = 30000;
+/** Node fires a setTimeout above 2^31 - 1 ms immediately, so long delays are clamped and re-armed. */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** A Database DeliveryID is stable across attempts; only DeliveryID + LeaseToken identifies one execution. */
+export declare function ExecutionKeyOf(delivery: ReceivedDelivery): string;
+export interface DeliveryExecutionOptions<TPayload extends WorkJson = WorkJson> {
+    Delivery: ReceivedDelivery<TPayload>;
+    Consumer: ITransportConsumer<TPayload>;
+    HandlerFactory: () => WorkHandler<TPayload>;
+    Policy: SubscriptionPolicy;
+    Log: WorkLogger;
+    Now?: () => number;
+    Random?: () => number;
+    /** Defaults to LEASE_EXPIRY_GRACE_MS. */
+    LeaseExpiryGraceMs?: number;
+    /** Defaults to DEFAULT_CANCEL_DRAIN_MS; ConsumerRuntime passes its ShutdownDrainMs. */
+    CancelDrainMs?: number;
+}
+/** Runs one handler for one delivery: context, lease heartbeats, lease horizon, processing cap, outcome, settle. */
+export declare class DeliveryExecution<TPayload extends WorkJson = WorkJson> {
+    private readonly options;
+    private readonly controller;
+    /** First abort reason; what the handler sees as Signal.reason. The flags below are independent of it. */
+    private abortReason;
+    private leaseLost;
+    private cancelled;
+    private capReached;
+    private shutdownRequested;
+    private heartbeatTimer;
+    private capTimer;
+    private horizonTimer;
+    private cancelDrainTimer;
+    private pendingHeartbeat;
+    /** Wall-clock instant this lease is good until; moves forward on every ExtendLease that returns Held. */
+    private leaseHorizonMs;
+    private capDeadlineMs;
+    private readonly horizonPassed;
+    private readonly cancelDrainElapsed;
+    constructor(options: DeliveryExecutionOptions<TPayload>);
+    private now;
+    get DeliveryID(): string;
+    get ExecutionKey(): string;
+    /** The first reason the handler was asked to stop, or null. */
+    get StopReason(): WorkAbortReason | null;
+    /** Requests the handler to stop. The signal keeps its first reason; a shutdown is remembered regardless. */
+    Abort(reason: WorkAbortReason): void;
+    Run(): Promise<SettleResult>;
+    private invokeHandler;
+    private buildContext;
+    /** A heartbeat still in flight decides whether we may settle, but never for longer than the lease itself. */
+    private awaitPendingHeartbeat;
+    private heartbeat;
+    private extendLease;
+    private onCancelled;
+    private acknowledgeCancel;
+    private startTimers;
+    /** Independent of heartbeats: fires when the lease (plus the skew allowance) runs out without a Held. */
+    private armHorizonTimer;
+    private onHorizon;
+    private armCapTimer;
+    private onProcessingCap;
+    /** Stops everything except the horizon timer, which must outlive a heartbeat that is still in flight. */
+    private stopWorkTimers;
+    private clearHeartbeatTimer;
+    private clearHorizonTimer;
+    private settle;
+    /**
+     * A settle that reports LeaseLost gets one AcknowledgeCancel attempt (spec 03 §3.2): a cancel that landed
+     * between the last heartbeat and this settle then frees its key now instead of at lease expiry. The
+     * acknowledgement is a no-op for every other cause of LeaseLost.
+     */
+    private settleSafely;
+    private logData;
+}
+//# sourceMappingURL=DeliveryExecution.d.ts.map

package/dist/runtime/DeliveryExecution.d.ts.map

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