@haywoodmarx/agent-pager 0.1.0

package/dist/src/messaging/notifications.d.ts

@@ -0,0 +1,231 @@
+import { type AgentId } from "../broker/protocol.js";
+/** Limits the number of accepted operator correlations represented by one body-free wake. */
+export declare const OPERATOR_CONTROL_CORRELATION_LIMIT = 64;
+/** Bounds retained scheduler diagnostics independently from durable state. */
+export declare const NOTIFICATION_OPERATIONAL_EVENT_LIMIT = 4096;
+/** Reports a controlled rejection at the body-free notification boundary. */
+export declare class NotificationValidationError extends Error {
+}
+/** Describes the notification behaviours supported by an adapter. */
+export type AdapterCapabilities = {
+    /** Reports whether the adapter accepts coalesced busy wakes. */
+    coalescing: boolean;
+    /** Identifies the newest protocol version understood by the adapter. */
+    maxProtocolVersion: 1;
+};
+/**
+ * A wake telling one agent its inbox changed. Carries no peer message body and must never gain
+ * one: a host-push delivery claims the messages itself when it handles the wake.
+ */
+type InboxChangedBase = {
+    /** Identifies this body-free inbox event. */
+    type: "inbox_changed";
+    /** Identifies the recipient agent. */
+    agentId: AgentId;
+    /** Orders inbox events within one broker epoch. */
+    sequence: number;
+    /** Identifies the broker epoch emitting the event. */
+    epoch: string;
+};
+/** Represents a durable-inbox wake without operator control state. */
+export type InboxMessageChanged = InboxChangedBase & {
+    /** Records why a durable inbox wake was emitted. */
+    reason: "queued" | "redelivery" | "resync" | "shed";
+    /** Identifies the durable message when the wake concerns one message. */
+    messageId?: string;
+};
+/** Represents a pure operator wake without any durable message identity. */
+export type OperatorPingChanged = InboxChangedBase & {
+    /** Records a body-free operator control wake. */
+    reason: "operator_ping";
+    /** Correlates the wake with its accepted operator command. */
+    controlId: string;
+    /** Preserves every additional command correlation represented by a coalesced wake. */
+    coalescedControlIds: string[];
+};
+/** Represents exactly one mutually exclusive message or operator-control wake. */
+export type InboxChanged = InboxMessageChanged | OperatorPingChanged;
+/** Records a message-related reason that may optionally carry one durable message identity. */
+export type InboxMessageReason = Exclude<InboxChanged["reason"], "operator_ping">;
+/** Classifies scheduler admission without claiming adapter delivery. */
+export type OperatorPingAdmission = {
+    /** Reports an exact durable retry for which no second wake was admitted. */
+    status: "already_accepted";
+    /** Correlates the skipped candidate wake. */
+    controlId: string;
+} | {
+    /** Reports immediate publication to the notification hub. */
+    status: "accepted";
+    /** Correlates the accepted command. */
+    controlId: string;
+    /** Carries the body-free wake published for the request. */
+    wake: OperatorPingChanged;
+} | {
+    /** Reports retention in a busy adapter's pending wake. */
+    status: "coalesced";
+    /** Correlates the accepted command retained in pending state. */
+    controlId: string;
+} | {
+    /** Reports scheduler rejection before hub publication. */
+    status: "budget_rejected";
+    /** Correlates the rejected command request. */
+    controlId: string;
+} | {
+    /** Reports rejection before an unbounded or duplicate busy correlation can be retained. */
+    status: "correlation_rejected";
+    /** Correlates the rejected command request. */
+    controlId: string;
+    /** Identifies the bounded correlation policy that rejected admission. */
+    reason: "duplicate_control_id" | "pending_control_limit" | "admission_in_progress";
+};
+/** Reports every independently published member of one busy-state release. */
+export type BusyWakeRelease = {
+    /** Identifies the fixed release outcome boundary. */
+    type: "busy_wake_release";
+    /** Carries the released message wake when one was admitted. */
+    message: InboxMessageChanged | null;
+    /** Carries the released operator wake when controls were admitted and the agent stayed available. */
+    operatorPing: OperatorPingChanged | null;
+};
+/** Identifies a subscriber invocation isolated from notification publication. */
+export type NotificationSubscriberFailure = {
+    /** Identifies the subscriber's target agent without retaining the thrown value. */
+    agentId: AgentId;
+    /** Identifies the event whose subscriber failed. */
+    sequence: number;
+};
+/** Describes a scheduler outcome retained for diagnostics. */
+export type NotificationEvent = {
+    /** Identifies a wake dropped to enforce a delivery limit. */
+    type: "wake_shed";
+    /** Identifies the affected agent. */
+    agentId: AgentId;
+    /** Records the limiting policy that shed the wake. */
+    reason: "wake_budget" | "duplicate_control_id" | "pending_control_limit";
+    /** Identifies the message whose wake was shed when available. */
+    messageId?: string;
+    /** Correlates operator control requests rejected by the scheduler. */
+    controlIds?: string[];
+} | {
+    /** Identifies a wake deferred because the adapter is busy. */
+    type: "wake_deferred";
+    /** Identifies the affected agent. */
+    agentId: AgentId;
+    /** Correlates operator control requests retained in pending state. */
+    controlIds?: string[];
+} | {
+    /** Identifies a wake successfully sent to an adapter. */
+    type: "wake_sent";
+    /** Identifies the affected agent. */
+    agentId: AgentId;
+    /** Records the event sequence that was sent. */
+    sequence: number;
+    /** Correlates operator control requests represented by the wake. */
+    controlIds?: string[];
+};
+/** Body-free adapter notification fan-out. */
+export declare class NotificationHub {
+    #private;
+    /**
+     * Constructs a notification hub for one broker epoch.
+     * @param epoch - Broker generation used to fence stale sessions.
+     * @param options - Optional non-retaining subscriber-failure observer.
+     */
+    constructor(epoch: string, options?: {
+        onSubscriberError?: (failure: NotificationSubscriberFailure) => void;
+    });
+    /**
+     * Publish an inbox change without storing message bodies or creating queue state.
+     * @param agentId - Recipient the inbox change is published for.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @param messageId - Message the change names, when it names one.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publish(agentId: AgentId, reason: InboxMessageReason, messageId?: string): InboxMessageChanged;
+    /**
+     * Publish a body-free operator control wake without creating peer delivery state.
+     * @param agentId - Stable identity of the requested target.
+     * @param controlId - Opaque correlation of the primary accepted command.
+     * @param coalescedControlIds - Additional accepted command correlations represented by this wake.
+     * @returns - Copy of the published event; changing it does not alter what subscribers received.
+     */
+    publishOperatorPing(agentId: AgentId, controlId: string, coalescedControlIds?: readonly string[]): OperatorPingChanged;
+    /**
+     * Subscribe an adapter to body-free notification events.
+     * @param agentId - Agent whose operational events the listener receives.
+     * @param listener - Callback invoked for each matching operational event.
+     * @returns - Unsubscribe callback that detaches the registered listener.
+     */
+    subscribe(agentId: AgentId, listener: (event: InboxChanged) => void): () => void;
+}
+/** Broker operations the scheduler reaches: outcome recording and queue inspection. */
+export interface NotificationBroker {
+    /** Record a notification outcome for a message. */
+    recordNotification(messageId: string, outcome: "delivered" | "shed" | "failed" | "deferred"): void;
+    /** Return whether an agent has queued messages. */
+    hasQueuedMessages(agentId: AgentId): boolean;
+}
+/** Broker notification scheduler for retry, coalescing, busy deferral, wake and correlation shedding, and operational events. */
+export declare class NotificationScheduler {
+    #private;
+    /**
+     * Constructs a scheduler over the notification broker and event hub.
+     * @param broker - Durable broker instance that owns message state.
+     * @param hub - Notification stream used to publish inbox changes.
+     * @param options - Clock, required so this scheduler shares the process's, plus optional policy.
+     */
+    constructor(broker: NotificationBroker, hub: NotificationHub, options: {
+        wakeBudget?: number;
+        wakeBudgetWindowMs?: number;
+        now: () => number;
+    });
+    /**
+     * Record adapter-declared capabilities used by the notification scheduler.
+     * @param agentId - Agent whose adapter capabilities are recorded.
+     * @param capabilities - Delivery capabilities reported by the adapter.
+     */
+    declareAdapter(agentId: AgentId, capabilities: AdapterCapabilities): void;
+    /**
+     * Notify an agent of durable inbox state without creating a second message queue.
+     * @param agentId - Agent notified of the inbox change.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @returns - Wake event when budget and capability policy allow delivery, otherwise null.
+     */
+    notify(agentId: AgentId, reason?: InboxMessageReason): InboxChanged | null;
+    /**
+     * Notify one message recipient and append adapter lifecycle outcomes for its receipt.
+     * @param messageId - Message the notification concerns.
+     * @param agentId - Recipient notified of the message.
+     * @param reason - Lifecycle reason attached to the inbox notification.
+     * @returns - Wake event tied to the durable message, or null when policy suppresses it.
+     */
+    notifyMessage(messageId: string | undefined, agentId: AgentId, reason?: InboxMessageReason): InboxChanged | null;
+    /**
+     * Admit a body-free operator ping without creating message delivery state.
+     * @param agentId - Stable identity of the requested target.
+     * @param controlId - Durable opaque correlation created with command acceptance.
+     * @param commitAcceptance - Synchronous durable acceptance performed after preflight and before scheduler mutation.
+     * @param resolveExisting - Read-only durable retry resolution performed before a rejected preflight becomes observable.
+     * @returns The admission outcome; `accepted` carries the published wake.
+     */
+    notifyOperatorPing(agentId: AgentId, controlId: string, commitAcceptance: () => "created" | "existing", resolveExisting: () => "absent" | "existing"): OperatorPingAdmission;
+    /**
+     * Record recipient delivery availability and coalesce many arrivals to one pending wake.
+     * @param agentId - Agent whose delivery availability changed.
+     * @param busy - Whether the agent is currently occupied.
+     * @returns - Every released message/control member, or null when no state changed.
+     */
+    setBusy(agentId: AgentId, busy: boolean): BusyWakeRelease | null;
+    /**
+     * Retry a dropped wake while durable messages remain unclaimed.
+     * @param agentId - Agent whose dropped wake is retried.
+     * @returns - Retry wake when queued work remains, otherwise null.
+     */
+    retryUnclaimed(agentId: AgentId): InboxChanged | null;
+    /**
+     * Return operational notification events.
+     * @returns - Copy of accumulated operational events, safe for caller inspection.
+     */
+    operationalEvents(): NotificationEvent[];
+}
+export {};