@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/plugin/outbox-drain-runtime.ts

@@ -0,0 +1,141 @@
+import type { OutboxEntry } from '../core/types.ts';
+import type { updateMinOutboxDelay } from '../messaging/outbound/queue-selectors.ts';
+import type { RetryRerouteDecision } from '../messaging/outbound/retry-policy.ts';
+import { createBncrOutboxDrainFailure } from './outbox-drain-failure.ts';
+import { createBncrOutboxDrainLoop } from './outbox-drain-loop.ts';
+import { createBncrOutboxDrainPostPush } from './outbox-drain-post-push.ts';
+
+type BncrOutboxDrainScheduleRuntime = {
+  scheduleAccountWait: (args: {
+    accountId: string;
+    messageId?: string;
+    source: string;
+    wait: number;
+    localNextDelay: number | null;
+    updateMinOutboxDelay: typeof updateMinOutboxDelay;
+  }) => number | null;
+  scheduleAccountYield: (args: {
+    accountId: string;
+    source: string;
+    localNextDelay: number | null;
+    updateMinOutboxDelay: typeof updateMinOutboxDelay;
+  }) => number | null;
+  mergeAccountNextDelay: (args: {
+    accountId: string;
+    localNextDelay: number;
+    globalNextDelay: number | null;
+    updateMinOutboxDelay: typeof updateMinOutboxDelay;
+    source: string;
+  }) => number | null;
+  scheduleFlushNextDrain: (args: { globalNextDelay: number; source: string }) => void;
+};
+
+type BncrOutboxDrainAckRuntime = {
+  logAckWaitStart: (args: {
+    entry: OutboxEntry;
+    requireAck: boolean;
+    ackTimeoutMs: number | null;
+    onlineNow: boolean;
+    recentInboundReachable: boolean;
+  }) => void;
+  handleAckTimeoutReroute: (args: {
+    accountId: string;
+    entry: OutboxEntry;
+    requireAck: boolean;
+    currentConnId: string;
+    availableConnIds: string[];
+    decision: RetryRerouteDecision;
+    localNextDelay: number | null;
+    ackTimeoutMs: number | null;
+    updateMinOutboxDelay: typeof updateMinOutboxDelay;
+  }) => { kind: 'dead-letter' } | { kind: 'retry'; localNextDelay: number | null };
+};
+
+type BncrOutboxDrainRuntime = {
+  bridgeId: string;
+  now: () => number;
+  asString: (value: unknown, fallback?: string) => string;
+  backoffMs: (retryCount: number) => number;
+  isPlainObject: (value: unknown) => value is Record<string, unknown>;
+  normalizeAccountId: (accountId: string) => string;
+  stopped: () => boolean;
+  outbox: Map<string, OutboxEntry>;
+  deadLetter: () => OutboxEntry[];
+  connectionsValues: () => IterableIterator<{
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    connectedAt: number;
+    lastSeenAt: number;
+    inboundOnly?: boolean;
+    outboundReady?: boolean;
+    preferredForOutbound?: boolean;
+    outboundReadyUntil?: number;
+    preferredForOutboundUntil?: number;
+    lastAckOkAt?: number;
+    lastPushTimeoutAt?: number;
+    pushFailureScore?: number;
+  }>;
+  gatewayContextAvailable: () => boolean;
+  messageAckWaiterCount: () => number;
+  fileAckWaiterCount: () => number;
+  activeConnectionCount: (accountId: string) => number;
+  getAccountPendingOutboxEntries: (accountId: string) => OutboxEntry[];
+  pushDrainRunningAccounts: Set<string>;
+  pushDrainRunningSinceByAccount: Map<string, number>;
+  pushDrainStuckWarnedAtByAccount: Map<string, number>;
+  isOnline: (accountId: string) => boolean;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isOutboundAckRequired: (accountId?: string) => boolean;
+  resolveMessageAckTimeoutMs: (accountId: string) => number;
+  waitForMessageAck: (messageId: string, waitMs: number) => Promise<'acked' | 'timeout'>;
+  logOutboxAckWait: (args: {
+    entry: OutboxEntry;
+    requireAck: boolean;
+    ackResult: 'acked' | 'timeout';
+    onlineNow: boolean;
+    recentInboundReachable: boolean;
+    ackTimeoutMs: number | null;
+  }) => void;
+  degradeOutboundCapability: (args: {
+    accountId: string;
+    connId?: string;
+    clientId?: string;
+    reason: string;
+  }) => void;
+  resolvePushConnIds: (accountId: string) => Iterable<string>;
+  sleepMs: (ms: number) => Promise<void>;
+  schedulePushDrain: (delayMs: number) => void;
+  outboxDrainSchedule: BncrOutboxDrainScheduleRuntime;
+  outboxDrainAck: BncrOutboxDrainAckRuntime;
+  tryPushEntry: (entry: OutboxEntry) => Promise<boolean>;
+  handleFileTransferPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  handleTextPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+  isPrePushGuardDeferral: (entry: OutboxEntry) => boolean;
+  moveToDeadLetter: (entry: OutboxEntry, reason: string) => void;
+  scheduleSave: () => void;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+  logWarn: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+  logError: (scope: string, message: string) => void;
+  flushTriggerTimer: string;
+  flushReasonScheduledDrain: string;
+  pushDrainExceptionRetryLimit: number;
+  pushDrainExceptionRetryDelayMs: number;
+  pushDrainStuckWarnMs: number;
+  pushDrainIntervalMs: number;
+  pushDrainAccountTimeBudgetMs: number;
+  pushDrainAccountBudget: number;
+  pushAckTimeoutMs: number;
+  maxRetry: number;
+  prePushGuardRetryDelayMs: number;
+};
+
+export function createBncrOutboxDrainRuntime(runtime: BncrOutboxDrainRuntime) {
+  const handlePushedDrainEntry = createBncrOutboxDrainPostPush(runtime);
+  const handleFailedDrainEntry = createBncrOutboxDrainFailure(runtime);
+
+  return createBncrOutboxDrainLoop(runtime, {
+    handlePushedDrainEntry,
+    handleFailedDrainEntry,
+  });
+}

package/src/plugin/outbox-drain-schedule.ts

@@ -0,0 +1,116 @@
+import { buildOutboxScheduleDebugInfo } from '../messaging/outbound/diagnostics.ts';
+import type { OutboundScheduleSource } from '../messaging/outbound/reasons.ts';
+
+function asScheduleSource(source: string): OutboundScheduleSource {
+  return source as OutboundScheduleSource;
+}
+
+export type BncrOutboxDrainScheduleRuntime = {
+  bridgeId: string;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+};
+
+export function createBncrOutboxDrainSchedule(runtime: BncrOutboxDrainScheduleRuntime) {
+  const logSchedule = (args: {
+    accountId?: string;
+    messageId?: string;
+    source: string;
+    wait?: number | null;
+    localNextDelay?: number | null;
+    globalNextDelay?: number | null;
+  }) => {
+    runtime.logInfo(
+      'outbox',
+      `schedule ${JSON.stringify(
+        buildOutboxScheduleDebugInfo({
+          bridgeId: runtime.bridgeId,
+          accountId: args.accountId,
+          messageId: args.messageId,
+          source: asScheduleSource(args.source),
+          wait: args.wait,
+          localNextDelay: args.localNextDelay,
+          globalNextDelay: args.globalNextDelay,
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+  };
+
+  const updateDelay = (
+    current: number | null,
+    wait: number | null,
+    updateMinOutboxDelay: (current: number | null, next: number | null) => number | null,
+  ) => updateMinOutboxDelay(current, wait);
+
+  const scheduleAccountYield = (args: {
+    accountId: string;
+    source: string;
+    localNextDelay: number | null;
+    updateMinOutboxDelay: (current: number | null, next: number | null) => number | null;
+  }) => {
+    const localNextDelay = updateDelay(args.localNextDelay, 0, args.updateMinOutboxDelay);
+    logSchedule({
+      accountId: args.accountId,
+      source: args.source,
+      wait: 0,
+      localNextDelay,
+    });
+    return localNextDelay;
+  };
+
+  const scheduleAccountWait = (args: {
+    accountId: string;
+    messageId?: string;
+    source: string;
+    wait: number;
+    localNextDelay: number | null;
+    updateMinOutboxDelay: (current: number | null, next: number | null) => number | null;
+  }) => {
+    const localNextDelay = updateDelay(args.localNextDelay, args.wait, args.updateMinOutboxDelay);
+    logSchedule({
+      accountId: args.accountId,
+      messageId: args.messageId,
+      source: args.source,
+      wait: args.wait,
+      localNextDelay,
+    });
+    return localNextDelay;
+  };
+
+  const mergeAccountNextDelay = (args: {
+    accountId: string;
+    localNextDelay: number;
+    globalNextDelay: number | null;
+    updateMinOutboxDelay: (current: number | null, next: number | null) => number | null;
+    source: string;
+  }) => {
+    const globalNextDelay = updateDelay(
+      args.globalNextDelay,
+      args.localNextDelay,
+      args.updateMinOutboxDelay,
+    );
+    logSchedule({
+      accountId: args.accountId,
+      source: args.source,
+      localNextDelay: args.localNextDelay,
+      globalNextDelay,
+    });
+    return globalNextDelay;
+  };
+
+  const scheduleFlushNextDrain = (args: { globalNextDelay: number; source: string }) => {
+    logSchedule({
+      source: args.source,
+      globalNextDelay: args.globalNextDelay,
+      wait: args.globalNextDelay,
+    });
+  };
+
+  return {
+    logSchedule,
+    scheduleAccountYield,
+    scheduleAccountWait,
+    mergeAccountNextDelay,
+    scheduleFlushNextDrain,
+  };
+}

package/src/plugin/outbox-file-push-flow.ts

@@ -0,0 +1,69 @@
+import { resolveFileTransferGuard } from '../core/outbox-file-transfer-guards.ts';
+import { prepareFileTransferRouteSelection } from '../core/outbox-file-transfer-prep.ts';
+import type { BncrConnection, OutboxEntry } from '../core/types.ts';
+import { selectOutboxFileTransferRouteCandidates } from '../messaging/outbound/queue-selectors.ts';
+
+export async function runBncrFileTransferOutboxPush(args: {
+  entry: OutboxEntry;
+  meta: Record<string, unknown>;
+  gatewayContext: unknown;
+  owner: BncrConnection | null;
+  resolvePushConnIds: (accountId: string) => Set<string>;
+  resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+  handleFileTransferPushGuardFailure: (args: {
+    entry: OutboxEntry;
+    guard: Exclude<ReturnType<typeof resolveFileTransferGuard>, { ok: true }>;
+  }) => void;
+  pushFileTransferSuccessPath: (args: {
+    entry: OutboxEntry;
+    meta: Record<string, unknown>;
+    owner: BncrConnection | null;
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    mediaUrl: string;
+  }) => Promise<void>;
+  handleFileTransferPushFailure: (args: { entry: OutboxEntry; error: unknown }) => void;
+}) {
+  const selection = prepareFileTransferRouteSelection({
+    entry: args.entry,
+    owner: args.owner,
+    resolvePushConnIds: args.resolvePushConnIds,
+    resolveRecentInboundConnIds: args.resolveRecentInboundConnIds,
+    hasRecentInboundReachability: args.hasRecentInboundReachability,
+    isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+    selectOutboxFileTransferRouteCandidates,
+  });
+  const guard = resolveFileTransferGuard({
+    gatewayContext: args.gatewayContext,
+    entry: args.entry,
+    owner: args.owner,
+    routeSelection: selection,
+    mediaUrl: String(args.meta.mediaUrl || '').trim(),
+  });
+  if (!guard.ok) {
+    args.handleFileTransferPushGuardFailure({
+      entry: args.entry,
+      guard,
+    });
+    return false;
+  }
+
+  try {
+    await args.pushFileTransferSuccessPath({
+      entry: args.entry,
+      meta: args.meta,
+      owner: args.owner,
+      connIds: guard.connIds,
+      recentInboundReachable: guard.recentInboundReachable,
+      routeReason: guard.routeReason,
+      mediaUrl: guard.mediaUrl,
+    });
+    return true;
+  } catch (error) {
+    args.handleFileTransferPushFailure({ entry: args.entry, error });
+    return false;
+  }
+}

package/src/plugin/outbox-push-route-runtime-group.ts

@@ -0,0 +1,81 @@
+import type { BncrConnection, OutboxEntry } from '../core/types.ts';
+import { createBncrOutboxPush } from './outbox-push.ts';
+import { createBncrOutboxRoute } from './outbox-route.ts';
+
+export function createBncrOutboxPushRouteRuntimeGroup(runtime: {
+  bridgeId: string;
+  pushEvent: string;
+  now: () => number;
+  connectTtlMs: number;
+  finiteNumberOr: (value: unknown, fallback: number) => number;
+  outboxSize: () => number;
+  gatewayBroadcastToConnIds: (
+    event: string,
+    payload: unknown,
+    connIds: ReadonlySet<string>,
+  ) => void;
+  recordOutboxPushSuccess: (args: {
+    entry: OutboxEntry;
+    connIds: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => void;
+  recordOutboxPushFailure: (args: {
+    entry: OutboxEntry;
+    error: unknown;
+    fallbackError: string;
+    persist?: boolean;
+  }) => void;
+  recordOutboxPrePushFailure: (args: {
+    entry: OutboxEntry;
+    lastError: string;
+    persist?: boolean;
+  }) => void;
+  recordPrePushGuardSkip: (args: { accountId: string; reason: string }) => void;
+  moveToDeadLetter: (entry: OutboxEntry, reason: string) => void;
+  activeConnectionCount: (accountId: string) => number;
+  connections: Map<string, BncrConnection>;
+  connectionsValues: () => Iterable<BncrConnection>;
+  activeConnectionByAccount: Map<string, string>;
+  resolveRecentInboundConnIds: (accountId: string) => Set<string>;
+  connectionKey: (accountId: string, clientId?: string) => string;
+  isRetryableFileTransferError: (value: unknown) => boolean;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+  buildActiveConnectionDebugList: (
+    accountId: string,
+    options?: { includeOutboundState?: boolean },
+  ) => unknown;
+}) {
+  const outboxPush = createBncrOutboxPush({
+    pushEvent: runtime.pushEvent,
+    outboxSize: runtime.outboxSize,
+    gatewayBroadcastToConnIds: runtime.gatewayBroadcastToConnIds,
+    recordOutboxPushSuccess: runtime.recordOutboxPushSuccess,
+    recordOutboxPushFailure: runtime.recordOutboxPushFailure,
+    recordOutboxPrePushFailure: runtime.recordOutboxPrePushFailure,
+    recordPrePushGuardSkip: runtime.recordPrePushGuardSkip,
+    moveToDeadLetter: runtime.moveToDeadLetter,
+    activeConnectionCount: runtime.activeConnectionCount,
+    connectionsValues: runtime.connectionsValues,
+    isRetryableFileTransferError: runtime.isRetryableFileTransferError,
+    logInfo: runtime.logInfo,
+  });
+
+  const outboxRoute = createBncrOutboxRoute({
+    bridgeId: runtime.bridgeId,
+    now: runtime.now,
+    connectTtlMs: runtime.connectTtlMs,
+    finiteNumberOr: runtime.finiteNumberOr,
+    connections: runtime.connections,
+    activeConnectionByAccount: runtime.activeConnectionByAccount,
+    resolveRecentInboundConnIds: runtime.resolveRecentInboundConnIds,
+    connectionKey: runtime.connectionKey,
+    logInfo: runtime.logInfo,
+    buildActiveConnectionDebugList: runtime.buildActiveConnectionDebugList,
+  });
+
+  return {
+    outboxPush,
+    outboxRoute,
+  };
+}

package/src/plugin/outbox-push.ts

@@ -0,0 +1,267 @@
+import {
+  buildFileTransferPushFailureArgs,
+  resolveFileTransferFailureState,
+} from '../core/outbox-file-transfer-failure.ts';
+import { buildTextPushFailureArgs } from '../core/outbox-text-push-failure.ts';
+import {
+  buildTextPushBroadcastPayload,
+  buildTextPushOkArgs,
+  buildTextPushRouteSelectArgs,
+  buildTextPushSuccessArgs,
+} from '../core/outbox-text-push-success.ts';
+import type { BncrConnection, OutboxEntry } from '../core/types.ts';
+import {
+  buildOutboxPushOkDebugInfo,
+  buildOutboxPushSkipDebugInfo,
+  buildOutboxRouteSelectDebugInfo,
+  buildPushFailureDebugInfo,
+} from '../messaging/outbound/diagnostics.ts';
+
+export type BncrOutboxPushRuntime = {
+  pushEvent: string;
+  outboxSize: () => number;
+  gatewayBroadcastToConnIds: (
+    event: string,
+    payload: unknown,
+    connIds: ReadonlySet<string>,
+  ) => void;
+  recordOutboxPushSuccess: (args: {
+    entry: OutboxEntry;
+    connIds: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => void;
+  recordOutboxPushFailure: (args: {
+    entry: OutboxEntry;
+    error: unknown;
+    fallbackError: string;
+    persist?: boolean;
+  }) => void;
+  recordOutboxPrePushFailure: (args: {
+    entry: OutboxEntry;
+    lastError: string;
+    persist?: boolean;
+  }) => void;
+  recordPrePushGuardSkip: (args: { accountId: string; reason: string }) => void;
+  moveToDeadLetter: (entry: OutboxEntry, reason: string) => void;
+  activeConnectionCount: (accountId: string) => number;
+  connectionsValues: () => Iterable<BncrConnection>;
+  isRetryableFileTransferError: (value: unknown) => boolean;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+};
+
+export function createBncrOutboxPush(runtime: BncrOutboxPushRuntime) {
+  const logOutboxPushOk = (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => {
+    runtime.logInfo('outbox', `push ${JSON.stringify(buildOutboxPushOkDebugInfo(args))}`, {
+      debugOnly: true,
+    });
+  };
+
+  const logOutboxPushSkip = (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    reason: string;
+    recentInboundReachable?: boolean;
+    routeReason?: string;
+    connIds?: Iterable<string>;
+    ownerConnId?: string;
+    ownerClientId?: string;
+  }) => {
+    runtime.recordPrePushGuardSkip({ accountId: args.accountId, reason: args.reason });
+    runtime.logInfo(
+      'outbox push skip',
+      `mid=${args.messageId}|q=${runtime.outboxSize()}|reason=${args.reason}${args.kind ? `|kind=${args.kind}` : ''}`,
+    );
+    runtime.logInfo(
+      'outbox',
+      `push-skip ${JSON.stringify(
+        buildOutboxPushSkipDebugInfo({
+          ...args,
+          activeConnectionCount: runtime.activeConnectionCount(args.accountId),
+          connections: runtime.connectionsValues(),
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+  };
+
+  const logOutboxRouteSelect = (args: {
+    messageId: string;
+    accountId: string;
+    kind?: 'file-transfer';
+    routeReason: string;
+    connIds: Iterable<string>;
+    ownerConnId: string;
+    ownerClientId: string;
+    recentInboundReachable: boolean;
+    event: string;
+  }) => {
+    runtime.logInfo(
+      'outbox',
+      `route-select ${JSON.stringify(buildOutboxRouteSelectDebugInfo(args))}`,
+      { debugOnly: true },
+    );
+  };
+
+  const logOutboxPushFailure = (args: {
+    messageId: string;
+    accountId: string;
+    retryCount: number;
+    kind?: 'file-transfer';
+    retryable?: boolean;
+    lastError?: string;
+  }) => {
+    runtime.logInfo('outbox', `push-fail ${JSON.stringify(buildPushFailureDebugInfo(args))}`, {
+      debugOnly: true,
+    });
+  };
+
+  const logOutboxPushOkSummary = (messageId: string) => {
+    runtime.logInfo('outbox push', `mid=${messageId}|q=${runtime.outboxSize()}`);
+  };
+
+  const logOutboxPushFailureSummary = (messageId: string, lastError?: string) => {
+    runtime.logInfo(
+      'outbox push fail',
+      `mid=${messageId}|q=${runtime.outboxSize()}|err=${lastError}`,
+    );
+  };
+
+  const pushTextSuccessPath = (args: {
+    entry: OutboxEntry;
+    owner: BncrConnection | null;
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    ownerConnId?: string;
+  }) => {
+    runtime.gatewayBroadcastToConnIds(
+      runtime.pushEvent,
+      buildTextPushBroadcastPayload({
+        payload: args.entry.payload,
+        messageId: args.entry.messageId,
+      }),
+      new Set(args.connIds),
+    );
+    logOutboxRouteSelect(
+      buildTextPushRouteSelectArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        routeReason: args.routeReason,
+        recentInboundReachable: args.recentInboundReachable,
+        owner: args.owner,
+        event: runtime.pushEvent,
+      }),
+    );
+    runtime.recordOutboxPushSuccess(
+      buildTextPushSuccessArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        ownerConnId: args.ownerConnId,
+        ownerClientId: args.ownerConnId ? args.owner?.clientId : undefined,
+      }),
+    );
+    logOutboxPushOkSummary(args.entry.messageId);
+    logOutboxPushOk(
+      buildTextPushOkArgs({
+        entry: args.entry,
+        connIds: args.connIds,
+        recentInboundReachable: args.recentInboundReachable,
+        event: runtime.pushEvent,
+      }),
+    );
+  };
+
+  const handleTextPushFailure = (args: { entry: OutboxEntry; error: unknown }) => {
+    runtime.recordOutboxPushFailure({
+      entry: args.entry,
+      error: args.error,
+      fallbackError: 'push-error',
+    });
+    logOutboxPushFailureSummary(args.entry.messageId, args.entry.lastError);
+    logOutboxPushFailure(buildTextPushFailureArgs({ entry: args.entry }));
+  };
+
+  const handleFileTransferPushFailure = (args: { entry: OutboxEntry; error: unknown }) => {
+    runtime.recordOutboxPushFailure({
+      entry: args.entry,
+      error: args.error,
+      fallbackError: 'file-transfer-error',
+      persist: true,
+    });
+    const failure = resolveFileTransferFailureState({
+      entry: args.entry,
+      error: args.error,
+      isRetryableFileTransferError: (value) => runtime.isRetryableFileTransferError(value),
+    });
+    logOutboxPushFailureSummary(args.entry.messageId, args.entry.lastError);
+    logOutboxPushFailure(
+      buildFileTransferPushFailureArgs({
+        entry: args.entry,
+        retryable: failure.retryable,
+      }),
+    );
+    if (!failure.retryable) {
+      runtime.moveToDeadLetter(args.entry, failure.deadLetterReason);
+    }
+  };
+
+  const handleFileTransferPushGuardFailure = (args: {
+    entry: OutboxEntry;
+    guard: {
+      reason: 'media-url-missing' | 'no-gateway-context' | 'no-active-connection';
+      lastError: string;
+      recentInboundReachable?: boolean;
+    };
+  }) => {
+    runtime.recordOutboxPrePushFailure({
+      entry: args.entry,
+      lastError: args.guard.lastError,
+      persist: true,
+    });
+    if (args.guard.reason === 'media-url-missing') {
+      logOutboxPushFailure({
+        messageId: args.entry.messageId,
+        accountId: args.entry.accountId,
+        retryCount: args.entry.retryCount,
+        kind: 'file-transfer',
+        lastError: args.entry.lastError,
+      });
+      return;
+    }
+    logOutboxPushSkip({
+      messageId: args.entry.messageId,
+      accountId: args.entry.accountId,
+      kind: 'file-transfer',
+      reason:
+        args.guard.reason === 'no-gateway-context' ? 'no-gateway-context' : 'no-active-connection',
+      recentInboundReachable:
+        args.guard.reason === 'no-active-connection'
+          ? args.guard.recentInboundReachable
+          : undefined,
+    });
+  };
+
+  return {
+    pushTextSuccessPath,
+    handleTextPushFailure,
+    handleFileTransferPushFailure,
+    handleFileTransferPushGuardFailure,
+    logOutboxPushSkip,
+    logOutboxRouteSelect,
+    logOutboxPushFailure,
+    logOutboxPushOk,
+    logOutboxPushOkSummary,
+    logOutboxPushFailureSummary,
+  };
+}