@xmoxmo/bncr 0.2.4 → 0.2.6

package/src/messaging/inbound/session-label.ts

@@ -0,0 +1,115 @@
+import {
+  recordSessionMetaFromInbound,
+  updateSessionStoreEntry,
+} from 'openclaw/plugin-sdk/session-store-runtime';
+import { emitBncrLogLine } from '../../core/logging.ts';
+
+type RecordInboundSessionFn = (args: any) => Promise<unknown> | unknown;
+
+export function buildBncrInboundSessionIdentityPatch(args: {
+  channelId: string;
+  accountId: string;
+  chatType: 'direct' | 'group';
+  displayTo: string;
+  senderId: string;
+}) {
+  const { channelId, accountId, chatType, displayTo, senderId } = args;
+  return {
+    label: displayTo,
+    channel: channelId,
+    chatType,
+    origin: {
+      label: displayTo,
+      provider: channelId,
+      surface: channelId,
+      chatType,
+      from: senderId,
+      to: displayTo,
+      accountId,
+    },
+    deliveryContext: {
+      channel: channelId,
+      to: displayTo,
+      accountId,
+    },
+    route: {
+      channel: channelId,
+      accountId,
+      target: { to: displayTo },
+    },
+    lastTo: displayTo,
+  };
+}
+
+function normalizeNonEmptyString(value: unknown): string | null {
+  const normalized = String(value ?? '').trim();
+  return normalized || null;
+}
+
+export async function correctBncrInboundSessionLabel(args: {
+  storePath: string;
+  sessionKey: string;
+  expectedLabel: string;
+}) {
+  const storePath = normalizeNonEmptyString(args.storePath);
+  const sessionKey = normalizeNonEmptyString(args.sessionKey);
+  const expectedLabel = normalizeNonEmptyString(args.expectedLabel);
+  if (!storePath || !sessionKey || !expectedLabel) return;
+
+  try {
+    await updateSessionStoreEntry({
+      storePath,
+      sessionKey,
+      update: (entry: any) => {
+        if (entry?.label === expectedLabel) return null;
+        return { label: expectedLabel };
+      },
+    });
+  } catch (err) {
+    emitBncrLogLine('warn', `[bncr] inbound session label correction failed: ${String(err)}`);
+  }
+}
+
+export async function recordAndPatchBncrInboundSessionEntry(args: {
+  storePath: string;
+  sessionKey: string;
+  ctx?: Record<string, unknown>;
+  patch: Record<string, unknown>;
+}) {
+  const storePath = normalizeNonEmptyString(args.storePath);
+  const sessionKey = normalizeNonEmptyString(args.sessionKey);
+  if (!storePath || !sessionKey) return;
+
+  try {
+    if (args.ctx) {
+      await recordSessionMetaFromInbound({
+        storePath,
+        sessionKey,
+        ctx: args.ctx as any,
+        createIfMissing: true,
+      });
+    }
+    await updateSessionStoreEntry({
+      storePath,
+      sessionKey,
+      update: () => args.patch,
+    });
+  } catch (err) {
+    emitBncrLogLine('warn', `[bncr] inbound session patch failed: ${String(err)}`);
+  }
+}
+
+export function wrapBncrInboundRecordSessionLabelCorrection(args: {
+  recordInboundSession: RecordInboundSessionFn;
+  expectedLabel: string;
+}): RecordInboundSessionFn {
+  return async (recordArgs: any) => {
+    const result = await args.recordInboundSession(recordArgs);
+    await correctBncrInboundSessionLabel({
+      storePath: recordArgs?.storePath,
+      sessionKey: recordArgs?.sessionKey,
+      expectedLabel: args.expectedLabel,
+    });
+    return result;
+  };
+}

package/src/messaging/outbound/diagnostics.ts

@@ -0,0 +1,262 @@
+import {
+  type OutboundScheduleSource,
+  OUTBOUND_TERMINAL_REASON,
+} from './reasons.ts';
+import type { RetryRerouteDecision } from './retry-policy.ts';
+
+export function buildOutboxScheduleDebugInfo(args: {
+  bridgeId: string;
+  accountId?: string | null;
+  // Account-local aggregated next delay after considering currently visible entries.
+  localNextDelay?: number | null;
+  // Bridge-global aggregated next delay after merging account-local scheduling decisions.
+  globalNextDelay?: number | null;
+  // Immediate wait observed for this specific scheduling event.
+  wait?: number | null;
+  source: OutboundScheduleSource;
+  messageId?: string;
+}) {
+  return {
+    bridge: args.bridgeId,
+    ...(args.accountId ? { accountId: args.accountId } : {}),
+    ...(args.messageId ? { messageId: args.messageId } : {}),
+    source: args.source,
+    ...(typeof args.wait === 'number' ? { wait: args.wait } : {}),
+    ...(typeof args.localNextDelay === 'number' ? { localNextDelay: args.localNextDelay } : {}),
+    ...(typeof args.globalNextDelay === 'number' ? { globalNextDelay: args.globalNextDelay } : {}),
+  };
+}
+
+export function buildOutboxPushSkipDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  reason: string;
+  recentInboundReachable?: boolean;
+  kind?: string;
+}) {
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    ...(args.kind ? { kind: args.kind } : {}),
+    reason: args.reason,
+    ...(typeof args.recentInboundReachable === 'boolean'
+      ? { recentInboundReachable: args.recentInboundReachable }
+      : {}),
+  };
+}
+
+export function buildOutboxRouteSelectDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  routeReason: string;
+  connIds: Iterable<string>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+  recentInboundReachable: boolean;
+  event: string;
+  kind?: string;
+}) {
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    ...(args.kind ? { kind: args.kind } : {}),
+    routeReason: args.routeReason,
+    connIds: Array.from(args.connIds),
+    ownerConnId: args.ownerConnId || '',
+    ownerClientId: args.ownerClientId || '',
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+  };
+}
+
+export function buildOutboxPushOkDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  connIds: Iterable<string>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+  recentInboundReachable: boolean;
+  event: string;
+  kind?: string;
+}) {
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    ...(args.kind ? { kind: args.kind } : {}),
+    connIds: Array.from(args.connIds),
+    ownerConnId: args.ownerConnId || '',
+    ownerClientId: args.ownerClientId || '',
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+  };
+}
+
+export function buildFlushDebugInfo(args: {
+  bridgeId: string;
+  accountId: string | null;
+  targetAccounts: string[];
+  outboxSize: number;
+  trigger: string;
+  reason?: string;
+}) {
+  return {
+    bridge: args.bridgeId,
+    accountId: args.accountId,
+    targetAccounts: [...args.targetAccounts],
+    outboxSize: args.outboxSize,
+    trigger: args.trigger,
+    reason: args.reason,
+  };
+}
+
+export function buildOutboxAckDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  requireAck: boolean;
+  ackResult: 'acked' | 'timeout';
+  onlineNow: boolean;
+  recentInboundReachable: boolean;
+  connIds?: Iterable<string>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+  sessionKey?: string;
+  to?: string;
+  ackStage?: string;
+  ackOutcome?: string;
+  reason?: string;
+  kind?: string;
+  event?: string;
+  ackTimeoutMs?: number;
+  adaptiveAckTimeoutEnabled?: boolean;
+}) {
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    ...(args.sessionKey ? { sessionKey: args.sessionKey } : {}),
+    ...(args.to ? { to: args.to } : {}),
+    ...(args.kind ? { kind: args.kind } : {}),
+    requireAck: args.requireAck,
+    ackResult: args.ackResult,
+    ackStage: args.ackStage || 'message',
+    ackOutcome: args.ackOutcome || args.ackResult,
+    ...(args.reason ? { reason: args.reason } : {}),
+    ...(typeof args.ackTimeoutMs === 'number' ? { ackTimeoutMs: args.ackTimeoutMs } : {}),
+    ...(typeof args.adaptiveAckTimeoutEnabled === 'boolean'
+      ? { adaptiveAckTimeoutEnabled: args.adaptiveAckTimeoutEnabled }
+      : {}),
+    onlineNow: args.onlineNow,
+    recentInboundReachable: args.recentInboundReachable,
+    ...(args.connIds ? { connIds: Array.from(args.connIds) } : {}),
+    ...(args.ownerConnId ? { ownerConnId: args.ownerConnId } : {}),
+    ...(args.ownerClientId ? { ownerClientId: args.ownerClientId } : {}),
+    ...(args.event ? { event: args.event } : {}),
+  };
+}
+
+export function buildRetryRerouteDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  currentConnId: string;
+  decision: RetryRerouteDecision;
+  availableConnIds: string[];
+}) {
+  if (args.decision.kind !== 'retry') {
+    return {
+      messageId: args.messageId,
+      accountId: args.accountId,
+      currentConnId: args.currentConnId,
+      availableConnIds: [...args.availableConnIds],
+      kind: args.decision.kind,
+      terminalReason: args.decision.terminalReason,
+      nextRetryCount: args.decision.nextRetryCount,
+      lastAttemptAt: args.decision.lastAttemptAt,
+    };
+  }
+
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    currentConnId: args.currentConnId,
+    attemptedConnIds: [...args.decision.attemptedConnIds],
+    availableConnIds: [...args.availableConnIds],
+    revalidatedConnIds: [...args.decision.revalidatedConnIds],
+    hasUntriedAlternative: args.decision.hasUntriedAlternative,
+    shouldFastReroute: args.decision.shouldFastReroute,
+    routeAttemptRound: args.decision.routeAttemptRound,
+    nextAttemptAt: args.decision.nextAttemptAt,
+    fastReroutePending: args.decision.fastReroutePending,
+    nextRetryCount: args.decision.nextRetryCount,
+    lastAttemptAt: args.decision.lastAttemptAt,
+    lastError: args.decision.lastError,
+    kind: args.decision.kind,
+  };
+}
+
+export function buildPushFailureDebugInfo(args: {
+  messageId: string;
+  accountId: string;
+  retryCount: number;
+  lastError?: string;
+  retryable?: boolean;
+  kind?: string;
+}) {
+  return {
+    messageId: args.messageId,
+    accountId: args.accountId,
+    ...(args.kind ? { kind: args.kind } : {}),
+    ...(typeof args.retryable === 'boolean' ? { retryable: args.retryable } : {}),
+    retryCount: args.retryCount,
+    error:
+      (typeof args.lastError === 'string' && args.lastError) ||
+      OUTBOUND_TERMINAL_REASON.PUSH_RETRY,
+  };
+}
+
+export function buildEnqueueFromReplyDebugInfo(args: {
+  accountId: string;
+  sessionKey: string;
+  route: { platform?: string; groupId?: string; userId?: string } | null | undefined;
+  payload: {
+    text: string;
+    mediaUrl: string;
+    mediaUrls?: string[];
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId: string;
+  };
+}) {
+  return {
+    accountId: args.accountId,
+    sessionKey: args.sessionKey,
+    route: {
+      platform: args.route?.platform,
+      groupId: args.route?.groupId,
+      userId: args.route?.userId,
+    },
+    payload: {
+      text: args.payload.text,
+      mediaUrl: args.payload.mediaUrl,
+      mediaUrls: args.payload.mediaUrls,
+      asVoice: args.payload.asVoice,
+      audioAsVoice: args.payload.audioAsVoice,
+      kind: args.payload.kind,
+      replyToId: args.payload.replyToId,
+    },
+  };
+}
+
+export function buildReplyMediaFallbackDebugInfo(args: {
+  sessionKey: string;
+  mediaUrl: string;
+  replyToId: string;
+  fallback: { text: string; reason: string };
+}) {
+  return {
+    sessionKey: args.sessionKey,
+    mediaUrl: args.mediaUrl,
+    replyToId: args.replyToId || undefined,
+    fallbackText: args.fallback.text,
+    reason: args.fallback.reason,
+  };
+}

package/src/messaging/outbound/media-dedupe.ts

@@ -0,0 +1,51 @@
+export type MediaDedupeCacheEntry = {
+  mediaUrl: string;
+  text: string;
+  replyToId: string;
+  createdAt: number;
+};
+
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function normalizeReplyToId(value: unknown): string {
+  return asString(value || '').trim();
+}
+
+export function normalizeMessageText(value: unknown): string {
+  return asString(value || '').trim();
+}
+
+export function shouldTreatReplyToAsSame(
+  currentReplyToId: string,
+  previousReplyToId: string,
+): boolean {
+  if (!currentReplyToId || !previousReplyToId) return true;
+  return currentReplyToId === previousReplyToId;
+}
+
+export function buildMediaTextFallback(params: {
+  currentText: string;
+  previousText: string;
+  currentReplyToId: string;
+  previousReplyToId: string;
+}): { text: string; reason: 'same-text-sent-checkmark' | 'text-changed-downgrade' } | null {
+  if (!shouldTreatReplyToAsSame(params.currentReplyToId, params.previousReplyToId)) {
+    return null;
+  }
+
+  if (params.currentText && params.currentText !== params.previousText) {
+    return {
+      text: params.currentText,
+      reason: 'text-changed-downgrade',
+    };
+  }
+
+  return {
+    text: '✅已发送',
+    reason: 'same-text-sent-checkmark',
+  };
+}

package/src/messaging/outbound/media.ts

@@ -1,3 +1,5 @@
+import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
+
 function asString(v: unknown, fallback = ''): string {
   if (typeof v === 'string') return v;
   if (v == null) return fallback;
@@ -64,7 +66,7 @@ export function buildBncrMediaOutboundFrame(params: {
     messageId: params.messageId,
     idempotencyKey: params.messageId,
     sessionKey: params.sessionKey,
-    replyToId: asString(params.replyToId || '').trim() || undefined,
+    replyToId: normalizeOutboundReplyToId({ kind: params.kind, replyToId: params.replyToId }) || undefined,
     message: {
       platform: params.route.platform,
       groupId: params.route.groupId,

package/src/messaging/outbound/queue-selectors.ts

@@ -0,0 +1,191 @@
+import type { BncrConnection, OutboxEntry } from '../../core/types.ts';
+
+export type OutboxRouteSelection = {
+  connIds: string[];
+  routeReason:
+    | 'owner'
+    | 'active-connections-unattempted-first'
+    | 'active-connections-revalidated'
+    | 'active-connections-all-visible'
+    | 'recent-inbound-fallback'
+    | 'none';
+  recentInboundReachable: boolean;
+  ownerConnId?: string;
+};
+
+export type OutboxFileTransferRouteSelection = {
+  connIds: string[];
+  routeReason:
+    | 'owner'
+    | 'active-connections'
+    | 'active-connections-reused'
+    | 'recent-inbound-fallback'
+    | 'none';
+  recentInboundReachable: boolean;
+  ownerConnId?: string;
+};
+
+function finiteNumberOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export function computeOutboxRetryWait(nextAttemptAt: number, nowMs: number): number {
+  return Math.max(0, finiteNumberOr(nextAttemptAt, 0) - finiteNumberOr(nowMs, 0));
+}
+
+export function updateMinOutboxDelay(currentDelay: number | null, candidateDelay: number | null): number | null {
+  if (candidateDelay == null) return currentDelay;
+  return currentDelay == null ? candidateDelay : Math.min(currentDelay, candidateDelay);
+}
+
+export function clampOutboxDrainDelay(delayMs: number): number {
+  return Math.max(0, Math.min(finiteNumberOr(delayMs, 0), 30_000));
+}
+
+export function selectOutboxTargetAccounts(args: {
+  accountId?: string | null;
+  outboxEntries: Iterable<OutboxEntry>;
+  normalizeAccountId: (accountId: string) => string;
+}): string[] {
+  const filterAcc = args.accountId ? args.normalizeAccountId(args.accountId) : null;
+  if (filterAcc) return [filterAcc];
+  return Array.from(
+    new Set(Array.from(args.outboxEntries).map((entry) => args.normalizeAccountId(entry.accountId))),
+  );
+}
+
+export function listAccountOutboxEntries(args: {
+  accountId: string;
+  outboxEntries: Iterable<OutboxEntry>;
+  normalizeAccountId: (accountId: string) => string;
+}): OutboxEntry[] {
+  return Array.from(args.outboxEntries)
+    .filter((entry) => args.normalizeAccountId(entry.accountId) === args.accountId)
+    .sort((a, b) => a.createdAt - b.createdAt);
+}
+
+export function findDueOutboxEntry(entries: OutboxEntry[], nowMs: number): OutboxEntry | null {
+  return entries.find((item) => item.nextAttemptAt <= nowMs) || null;
+}
+
+export function computeNextOutboxDelay(entries: OutboxEntry[], nowMs: number): number | null {
+  if (!entries.length) return null;
+  const due = findDueOutboxEntry(entries, nowMs);
+  if (due) return 0;
+  return Math.max(0, entries[0].nextAttemptAt - nowMs);
+}
+
+export function buildOutboxOnlineDebugInfo(args: {
+  bridgeId: string;
+  accountId: string;
+  online: boolean;
+  recentInboundReachable: boolean;
+  connections: Iterable<BncrConnection>;
+}) {
+  return {
+    bridge: args.bridgeId,
+    accountId: args.accountId,
+    online: args.online,
+    recentInboundReachable: args.recentInboundReachable,
+    connections: Array.from(args.connections).map((c) => ({
+      accountId: c.accountId,
+      connId: c.connId,
+      clientId: c.clientId,
+      lastSeenAt: c.lastSeenAt,
+    })),
+  };
+}
+
+export function selectOutboxFileTransferRouteCandidates(args: {
+  routeCandidates: Iterable<string>;
+  attemptedConnIds: Iterable<string>;
+  recentInboundConnIds: Iterable<string>;
+  ownerConnId?: string;
+  recentInboundReachable: boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+}): OutboxFileTransferRouteSelection {
+  const routeCandidates = Array.from(args.routeCandidates);
+  const attemptedConnIds = new Set(Array.from(args.attemptedConnIds));
+  const filteredCandidates = routeCandidates.filter(
+    (connId) => !attemptedConnIds.has(connId) || args.isRevalidatedAttemptedConn(connId),
+  );
+  const ownerConnId =
+    args.ownerConnId && !attemptedConnIds.has(args.ownerConnId) ? args.ownerConnId : undefined;
+  let connIds = ownerConnId ? [ownerConnId] : filteredCandidates.length > 0 ? filteredCandidates : routeCandidates;
+  let routeReason: OutboxFileTransferRouteSelection['routeReason'] = ownerConnId
+    ? 'owner'
+    : connIds.length > 0
+      ? filteredCandidates.length > 0
+        ? 'active-connections'
+        : 'active-connections-reused'
+      : args.recentInboundReachable
+        ? 'recent-inbound-fallback'
+        : 'none';
+
+  if (!connIds.length && args.recentInboundReachable) {
+    const recentInboundConnIds = Array.from(args.recentInboundConnIds);
+    const filteredRecentInboundConnIds = recentInboundConnIds.filter(
+      (connId) => !attemptedConnIds.has(connId),
+    );
+    connIds = filteredRecentInboundConnIds.length > 0 ? filteredRecentInboundConnIds : recentInboundConnIds;
+    routeReason = connIds.length > 0 ? 'recent-inbound-fallback' : 'none';
+  }
+
+  return {
+    connIds,
+    routeReason,
+    recentInboundReachable: args.recentInboundReachable,
+    ...(ownerConnId ? { ownerConnId } : {}),
+  };
+}
+
+export function selectOutboxRouteCandidates(args: {
+  routeCandidates: Iterable<string>;
+  attemptedConnIds: Iterable<string>;
+  recentInboundConnIds: Iterable<string>;
+  ownerConnId?: string;
+  recentInboundReachable: boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+}): OutboxRouteSelection {
+  const routeCandidates = Array.from(args.routeCandidates);
+  const attemptedConnIds = new Set(Array.from(args.attemptedConnIds));
+  const unattemptedCandidates = routeCandidates.filter((connId) => !attemptedConnIds.has(connId));
+  const revalidatedCandidates = routeCandidates.filter(
+    (connId) => attemptedConnIds.has(connId) && args.isRevalidatedAttemptedConn(connId),
+  );
+  const preferredCandidates = unattemptedCandidates.length > 0 ? unattemptedCandidates : routeCandidates;
+  const ownerConnId =
+    args.ownerConnId && preferredCandidates.includes(args.ownerConnId) ? args.ownerConnId : undefined;
+  let connIds = ownerConnId ? [ownerConnId] : preferredCandidates;
+  let routeReason: OutboxRouteSelection['routeReason'] = ownerConnId
+    ? 'owner'
+    : connIds.length > 0
+      ? unattemptedCandidates.length > 0
+        ? 'active-connections-unattempted-first'
+        : revalidatedCandidates.length > 0
+          ? 'active-connections-revalidated'
+          : 'active-connections-all-visible'
+      : args.recentInboundReachable
+        ? 'recent-inbound-fallback'
+        : 'none';
+
+  if (!connIds.length && args.recentInboundReachable) {
+    const recentInboundConnIds = Array.from(args.recentInboundConnIds);
+    const unattemptedRecentInboundConnIds = recentInboundConnIds.filter(
+      (connId) => !attemptedConnIds.has(connId),
+    );
+    connIds =
+      unattemptedRecentInboundConnIds.length > 0
+        ? unattemptedRecentInboundConnIds
+        : recentInboundConnIds;
+    routeReason = connIds.length > 0 ? 'recent-inbound-fallback' : 'none';
+  }
+
+  return {
+    connIds,
+    routeReason,
+    recentInboundReachable: args.recentInboundReachable,
+    ...(ownerConnId ? { ownerConnId } : {}),
+  };
+}

package/src/messaging/outbound/reasons.ts

@@ -0,0 +1,52 @@
+export const OUTBOUND_DEGRADE_REASON = {
+  ACK_TIMEOUT: 'ack-timeout',
+  PUSH_UNCONFIRMED: 'push-unconfirmed',
+} as const;
+
+export const OUTBOUND_TERMINAL_REASON = {
+  PUSH_ACK_TIMEOUT: 'push-ack-timeout',
+  PUSH_DELIVERY_UNCONFIRMED: 'push-delivery-unconfirmed',
+  PUSH_RETRY_LIMIT: 'push-retry-limit',
+  PUSH_RETRY: 'push-retry',
+  FILE_ACK_TIMEOUT: 'file-ack-timeout',
+} as const;
+
+export const OUTBOUND_FLUSH_REASON = {
+  SCHEDULED_DRAIN: 'scheduled-drain',
+  WS_ONLINE: 'ws-online',
+  MESSAGE_ACKED: 'message-acked',
+  ACTIVITY_HEARTBEAT: 'activity-heartbeat',
+  INBOUND_ACCEPTED: 'inbound-accepted',
+} as const;
+
+export const OUTBOUND_FLUSH_TRIGGER = {
+  TIMER: 'timer',
+  CONNECT: 'connect',
+  ACK_OK: 'ack-ok',
+  ACTIVITY: 'activity',
+  INBOUND: 'inbound',
+} as const;
+
+// Scheduling debug sources describe where a next-drain wait came from.
+// They are observability taxonomy only; do not derive runtime behavior from them.
+export const OUTBOUND_SCHEDULE_SOURCE = {
+  // Single pending timer was armed by schedulePushDrain(...).
+  SCHEDULE_PUSH_DRAIN: 'schedule-push-drain',
+  // Current account has queued work, but nothing is due yet.
+  ACCOUNT_NO_DUE_ENTRY: 'account-no-due-entry',
+  // Ack-timeout / reroute path kept entry in outbox and scheduled a retry.
+  RETRY_REROUTE_WAIT: 'retry-reroute-wait',
+  // Direct push failure kept entry in outbox and scheduled backoff.
+  PUSH_FAIL_WAIT: 'push-fail-wait',
+  // Per-account flush processed its single-run item budget and yielded to the next drain.
+  ACCOUNT_BUDGET_YIELD: 'account-budget-yield',
+  // Per-account flush spent its single-run time budget and yielded to the next drain.
+  ACCOUNT_TIME_BUDGET_YIELD: 'account-time-budget-yield',
+  // Account-local next delay was merged into bridge-global next delay.
+  ACCOUNT_NEXT_DELAY_MERGE: 'account-next-delay-merge',
+  // flushPushQueue(...) finished and armed the next bridge-level drain.
+  FLUSH_NEXT_DRAIN: 'flush-next-drain',
+} as const;
+
+export type OutboundScheduleSource =
+  (typeof OUTBOUND_SCHEDULE_SOURCE)[keyof typeof OUTBOUND_SCHEDULE_SOURCE];