@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/bootstrap/register-runtime-gateway.ts

@@ -0,0 +1,129 @@
+import { emitBncrLogLine } from '../core/logging.ts';
+import type { BridgeRegisterStateCarrier } from './register-runtime-helpers.ts';
+import type { ChannelModule } from './runtime-loader.ts';
+
+type OpenClawPluginApi = Parameters<ChannelModule['createBncrBridge']>[0];
+type BridgeSingleton = ReturnType<ChannelModule['createBncrBridge']>;
+type BridgeGatewayHandlerContext = Parameters<BridgeSingleton['handleConnect']>[0];
+type BridgeGatewayHandlerResult = Awaited<ReturnType<BridgeSingleton['handleConnect']>>;
+type BridgeStateReader = { gatewayPid?: number; getBridgeId?: () => string };
+type OpenClawGatewayMethodMirror = {
+  name?: string;
+  handler?: (opts: BridgeGatewayHandlerContext) => unknown;
+};
+type OpenClawPluginApiWithGatewayMirror = OpenClawPluginApi & {
+  methods?: OpenClawGatewayMethodMirror[];
+};
+
+export type BncrGatewayMethodName =
+  | 'bncr.connect'
+  | 'bncr.inbound'
+  | 'bncr.activity'
+  | 'bncr.ack'
+  | 'bncr.diagnostics'
+  | 'bncr.deadLetter.inspect'
+  | 'bncr.deadLetter.prune'
+  | 'bncr.file.init'
+  | 'bncr.file.chunk'
+  | 'bncr.file.complete'
+  | 'bncr.file.abort'
+  | 'bncr.file.ack';
+
+export function createBncrGatewayMethodRegistry(runtime: {
+  getRegisterMeta: (api: OpenClawPluginApi) => {
+    methods?: Set<string>;
+    registryFingerprint?: string;
+  };
+  getRegistryFingerprint: (api: OpenClawPluginApi) => string;
+  getGatewayRuntime: () => {
+    currentBridge?: BridgeSingleton;
+    registeredMethodsByRegistry: Map<string, Set<BncrGatewayMethodName>>;
+  };
+  gatewayMethodDispatchers: Record<
+    BncrGatewayMethodName,
+    (bridge: BridgeSingleton, opts: BridgeGatewayHandlerContext) => BridgeGatewayHandlerResult
+  >;
+  getBridgeRegisterStateCarrier: (bridge: BridgeSingleton) => BridgeRegisterStateCarrier;
+}) {
+  const dispatchGatewayMethod = (
+    name: BncrGatewayMethodName,
+    opts: BridgeGatewayHandlerContext,
+  ) => {
+    const gatewayRuntime = runtime.getGatewayRuntime();
+    const bridge = gatewayRuntime.currentBridge;
+    if (!bridge) {
+      throw new Error(`bncr gateway runtime unavailable for ${name}`);
+    }
+    try {
+      return runtime.gatewayMethodDispatchers[name](bridge, opts);
+    } catch (error) {
+      const state = runtime.getBridgeRegisterStateCarrier(bridge) as BridgeStateReader;
+      const detail =
+        error instanceof Error
+          ? { name: error.name, message: error.message, stack: error.stack || null }
+          : { name: 'NonError', message: String(error), stack: null };
+      emitBncrLogLine(
+        'error',
+        `[bncr] gateway method error method=${name}|bridgeId=${state.getBridgeId?.() || '-'}|gatewayPid=${state.gatewayPid ?? '-'}|err=${detail.message}`,
+      );
+      emitBncrLogLine(
+        'error',
+        `[bncr] gateway method error ${JSON.stringify({
+          method: name,
+          bridgeId: state.getBridgeId?.() || null,
+          gatewayPid: state.gatewayPid ?? null,
+          detail,
+        })}`,
+        { debugOnly: true },
+        () => false,
+      );
+      throw error;
+    }
+  };
+
+  const mirrorGatewayMethodForMockApi = (
+    api: OpenClawPluginApiWithGatewayMirror,
+    name: BncrGatewayMethodName,
+  ) => {
+    if (!Array.isArray(api?.methods)) return;
+    if (api.methods.some((item) => item?.name === name)) return;
+    api.methods.push({ name, handler: (opts) => dispatchGatewayMethod(name, opts) });
+  };
+
+  const ensureGatewayMethodRegistered = (
+    api: OpenClawPluginApiWithGatewayMirror,
+    name: BncrGatewayMethodName,
+    debugLog: (...args: unknown[]) => void,
+  ) => {
+    const meta = runtime.getRegisterMeta(api);
+    const gatewayRuntime = runtime.getGatewayRuntime();
+    const registryFingerprint = meta.registryFingerprint || runtime.getRegistryFingerprint(api);
+    let registryMethods = gatewayRuntime.registeredMethodsByRegistry.get(registryFingerprint);
+    if (!registryMethods) {
+      registryMethods = new Set<BncrGatewayMethodName>();
+      gatewayRuntime.registeredMethodsByRegistry.set(registryFingerprint, registryMethods);
+    }
+    if (meta.methods?.has(name)) {
+      debugLog(`register method skip ${name} (already registered on this api)`);
+      return;
+    }
+    if (registryMethods.has(name)) {
+      mirrorGatewayMethodForMockApi(api, name);
+      meta.methods?.add(name);
+      debugLog(`register method reuse ${name} (already registered in registry)`);
+      return;
+    }
+    api.registerGatewayMethod(name, (opts: BridgeGatewayHandlerContext) =>
+      dispatchGatewayMethod(name, opts),
+    );
+    mirrorGatewayMethodForMockApi(api, name);
+    registryMethods.add(name);
+    meta.methods?.add(name);
+    debugLog(`register method ok ${name}`);
+  };
+
+  return {
+    dispatchGatewayMethod,
+    ensureGatewayMethodRegistered,
+  };
+}

package/src/bootstrap/register-runtime-helpers.ts

@@ -0,0 +1,140 @@
+export type BridgeOwner = {
+  moduleEpoch: string;
+  bridgeFactoryId: string;
+  apiInstanceId: string;
+  registryFingerprint: string;
+  registrationMode?: string;
+};
+
+export type BridgeRegisterStateSnapshot = {
+  registerCount: number;
+  apiGeneration: number;
+  firstRegisterAt: number | null;
+  lastRegisterAt: number | null;
+  lastApiRebindAt: number | null;
+  pluginSource: string | null;
+  pluginVersion: string | null;
+  lastApiInstanceId: string | null;
+  lastRegistryFingerprint: string | null;
+  lastDriftSnapshot: unknown;
+  registerTraceRecent: Array<Record<string, unknown>>;
+};
+
+export type BridgeRegisterStateCarrier = {
+  registerCount?: number;
+  apiGeneration?: number;
+  firstRegisterAt?: number | null;
+  lastRegisterAt?: number | null;
+  lastApiRebindAt?: number | null;
+  pluginSource?: string | null;
+  pluginVersion?: string | null;
+  lastApiInstanceId?: string | null;
+  lastRegistryFingerprint?: string | null;
+  lastDriftSnapshot?: unknown;
+  registerTraceRecent?: Array<Record<string, unknown>>;
+  gatewayPid?: number;
+};
+
+export function getProcessOwnerApiInstanceId(args: {
+  serviceOwnerApiInstanceId?: string;
+  channelOwnerApiInstanceId?: string;
+}) {
+  return args.serviceOwnerApiInstanceId || args.channelOwnerApiInstanceId || undefined;
+}
+
+export function sameBridgeOwner(left?: BridgeOwner, right?: BridgeOwner) {
+  if (!left || !right) return false;
+  return (
+    left.moduleEpoch === right.moduleEpoch &&
+    left.bridgeFactoryId === right.bridgeFactoryId &&
+    left.apiInstanceId === right.apiInstanceId &&
+    left.registryFingerprint === right.registryFingerprint
+  );
+}
+
+export function snapshotBridgeRegisterState(
+  bridge?: BridgeRegisterStateCarrier,
+): BridgeRegisterStateSnapshot | null {
+  if (!bridge) return null;
+  return {
+    registerCount: Number(bridge.registerCount || 0),
+    apiGeneration: Number(bridge.apiGeneration || 0),
+    firstRegisterAt:
+      typeof bridge.firstRegisterAt === 'number'
+        ? bridge.firstRegisterAt
+        : (bridge.firstRegisterAt ?? null),
+    lastRegisterAt:
+      typeof bridge.lastRegisterAt === 'number'
+        ? bridge.lastRegisterAt
+        : (bridge.lastRegisterAt ?? null),
+    lastApiRebindAt:
+      typeof bridge.lastApiRebindAt === 'number'
+        ? bridge.lastApiRebindAt
+        : (bridge.lastApiRebindAt ?? null),
+    pluginSource: typeof bridge.pluginSource === 'string' ? bridge.pluginSource : null,
+    pluginVersion: typeof bridge.pluginVersion === 'string' ? bridge.pluginVersion : null,
+    lastApiInstanceId:
+      typeof bridge.lastApiInstanceId === 'string' ? bridge.lastApiInstanceId : null,
+    lastRegistryFingerprint:
+      typeof bridge.lastRegistryFingerprint === 'string' ? bridge.lastRegistryFingerprint : null,
+    lastDriftSnapshot: bridge.lastDriftSnapshot ?? null,
+    registerTraceRecent: Array.isArray(bridge.registerTraceRecent)
+      ? bridge.registerTraceRecent.map((trace) => ({ ...trace }))
+      : [],
+  };
+}
+
+export function hydrateBridgeRegisterState<T extends BridgeRegisterStateCarrier>(
+  bridge: T,
+  snapshot: BridgeRegisterStateSnapshot | null,
+) {
+  if (!snapshot) return bridge;
+  bridge.registerCount = snapshot.registerCount;
+  bridge.apiGeneration = snapshot.apiGeneration;
+  bridge.firstRegisterAt = snapshot.firstRegisterAt;
+  bridge.lastRegisterAt = snapshot.lastRegisterAt;
+  bridge.lastApiRebindAt = snapshot.lastApiRebindAt;
+  bridge.pluginSource = snapshot.pluginSource;
+  bridge.pluginVersion = snapshot.pluginVersion;
+  bridge.lastApiInstanceId = snapshot.lastApiInstanceId;
+  bridge.lastRegistryFingerprint = snapshot.lastRegistryFingerprint;
+  bridge.lastDriftSnapshot = snapshot.lastDriftSnapshot;
+  bridge.registerTraceRecent = snapshot.registerTraceRecent.map((trace) => ({ ...trace }));
+  return bridge;
+}
+
+export function shouldAdoptProcessOwner(args: {
+  apiInstanceId: string;
+  serviceRegistered?: boolean;
+  channelRegistered?: boolean;
+  serviceOwnerApiInstanceId?: string;
+  channelOwnerApiInstanceId?: string;
+}) {
+  const existingOwnerApiInstanceId = getProcessOwnerApiInstanceId({
+    serviceOwnerApiInstanceId: args.serviceOwnerApiInstanceId,
+    channelOwnerApiInstanceId: args.channelOwnerApiInstanceId,
+  });
+  const hasSingletonOwner = Boolean(args.serviceRegistered) || Boolean(args.channelRegistered);
+
+  if (!hasSingletonOwner) {
+    return {
+      adoptOwner: true,
+      existingOwnerApiInstanceId,
+      reason: 'no-singleton-owner',
+    };
+  }
+
+  if (existingOwnerApiInstanceId && existingOwnerApiInstanceId === args.apiInstanceId) {
+    return {
+      adoptOwner: true,
+      existingOwnerApiInstanceId,
+      reason: 'same-owner-api',
+    };
+  }
+
+  return {
+    adoptOwner: false,
+    existingOwnerApiInstanceId,
+    reason: 'singleton-owned-by-other-api',
+  };
+}

package/src/bootstrap/register-runtime-singleton.ts

@@ -0,0 +1,137 @@
+import {
+  type BridgeOwner,
+  type BridgeRegisterStateCarrier,
+  hydrateBridgeRegisterState,
+  sameBridgeOwner,
+  snapshotBridgeRegisterState,
+} from './register-runtime-helpers.ts';
+import type { ChannelModule, LoadedRuntime } from './runtime-loader.ts';
+
+type OpenClawPluginApi = Parameters<ChannelModule['createBncrBridge']>[0];
+type BridgeSingleton = ReturnType<ChannelModule['createBncrBridge']>;
+type BridgeOwnedCarrier = BridgeRegisterStateCarrier & {
+  [key: symbol]: unknown;
+  stopService?: () => Promise<unknown> | unknown;
+  bindApi?: (api: OpenClawPluginApi) => void;
+  bindRuntimePaths?: (paths: { pluginRoot: string; pluginFile: string }) => void;
+};
+type GlobalBridgeStore = typeof globalThis & { __bncrBridge?: BridgeSingleton };
+
+function isBridgeOwner(value: unknown): value is BridgeOwner {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      'moduleEpoch' in value &&
+      'bridgeFactoryId' in value &&
+      'apiInstanceId' in value &&
+      'registryFingerprint' in value,
+  );
+}
+
+function getBridgeOwnedCarrier(bridge: BridgeSingleton): BridgeOwnedCarrier {
+  return bridge as unknown as BridgeOwnedCarrier;
+}
+
+function getBridgeRegisterStateCarrier(bridge: BridgeSingleton): BridgeRegisterStateCarrier {
+  return bridge as unknown as BridgeRegisterStateCarrier;
+}
+
+export function createBncrBridgeSingletonManager(runtime: {
+  bridgeOwnerSymbol: symbol;
+  pluginRoot: string;
+  pluginFile: string;
+  loadBncrRuntimeSync: () => LoadedRuntime;
+  getBridgeOwner: (api: OpenClawPluginApi, loaded: LoadedRuntime) => BridgeOwner;
+}) {
+  const assignBridgeOwner = <T extends BridgeSingleton>(bridge: T, owner: BridgeOwner) => {
+    getBridgeOwnedCarrier(bridge)[runtime.bridgeOwnerSymbol] = owner;
+    return bridge;
+  };
+
+  const getBridgeSingleton = (api: OpenClawPluginApi) => {
+    const loaded = runtime.loadBncrRuntimeSync();
+    const g = globalThis as GlobalBridgeStore;
+    const owner = runtime.getBridgeOwner(api, loaded);
+    const previousOwnerRaw = g.__bncrBridge
+      ? getBridgeOwnedCarrier(g.__bncrBridge)[runtime.bridgeOwnerSymbol]
+      : undefined;
+    const previousOwner = isBridgeOwner(previousOwnerRaw) ? previousOwnerRaw : undefined;
+
+    let created = false;
+    let rebuilt = false;
+
+    if (g.__bncrBridge) {
+      const mustRebuild =
+        !sameBridgeOwner(previousOwner, owner) &&
+        (previousOwner?.moduleEpoch !== owner.moduleEpoch ||
+          previousOwner?.bridgeFactoryId !== owner.bridgeFactoryId ||
+          previousOwner?.registrationMode !== owner.registrationMode ||
+          previousOwner?.apiInstanceId !== owner.apiInstanceId ||
+          previousOwner?.registryFingerprint !== owner.registryFingerprint);
+
+      if (mustRebuild) {
+        const registerState = snapshotBridgeRegisterState(
+          getBridgeRegisterStateCarrier(g.__bncrBridge),
+        );
+        try {
+          g.__bncrBridge.stopService?.();
+        } catch {
+          // ignore stop errors during hot-restart recovery
+        }
+        const rebuiltBridge = assignBridgeOwner(
+          loaded.createBncrBridge(api, {
+            pluginRoot: runtime.pluginRoot,
+            pluginFile: runtime.pluginFile,
+          }),
+          owner,
+        );
+        hydrateBridgeRegisterState(getBridgeRegisterStateCarrier(rebuiltBridge), registerState);
+        g.__bncrBridge = rebuiltBridge;
+        created = true;
+        rebuilt = true;
+      } else {
+        g.__bncrBridge.bindApi?.(api);
+        assignBridgeOwner(g.__bncrBridge, owner);
+      }
+    } else {
+      g.__bncrBridge = assignBridgeOwner(
+        loaded.createBncrBridge(api, {
+          pluginRoot: runtime.pluginRoot,
+          pluginFile: runtime.pluginFile,
+        }),
+        owner,
+      );
+      created = true;
+    }
+
+    g.__bncrBridge?.bindRuntimePaths?.({
+      pluginRoot: runtime.pluginRoot,
+      pluginFile: runtime.pluginFile,
+    });
+
+    return { bridge: g.__bncrBridge, runtime: loaded, created, rebuilt, owner, previousOwner };
+  };
+
+  const getExistingBridgeSingleton = () => {
+    const g = globalThis as GlobalBridgeStore;
+    return g.__bncrBridge;
+  };
+
+  const getBridgeOwnerFromBridge = (bridge?: BridgeSingleton): BridgeOwner | undefined => {
+    if (!bridge) return undefined;
+    const bridgeCarrier = getBridgeOwnedCarrier(bridge);
+    for (const symbol of Object.getOwnPropertySymbols(bridge)) {
+      const owner = bridgeCarrier[symbol];
+      if (isBridgeOwner(owner)) return owner;
+    }
+    return undefined;
+  };
+
+  return {
+    assignBridgeOwner,
+    getBridgeRegisterStateCarrier,
+    getBridgeSingleton,
+    getExistingBridgeSingleton,
+    getBridgeOwnerFromBridge,
+  };
+}

package/src/bootstrap/register-runtime.ts

@@ -0,0 +1,201 @@
+import {
+  type BncrGatewayMethodName,
+  createBncrGatewayMethodRegistry,
+} from './register-runtime-gateway.ts';
+import {
+  type BridgeOwner,
+  type BridgeRegisterStateCarrier,
+  shouldAdoptProcessOwner,
+} from './register-runtime-helpers.ts';
+import { createBncrBridgeSingletonManager } from './register-runtime-singleton.ts';
+import {
+  type ChannelModule,
+  type LoadedRuntime,
+  loadBncrRuntimeSync,
+  pluginFile,
+  pluginRoot,
+} from './runtime-loader.ts';
+
+type OpenClawPluginApi = Parameters<ChannelModule['createBncrBridge']>[0];
+type BridgeSingleton = ReturnType<ChannelModule['createBncrBridge']>;
+type BridgeGatewayHandlerContext = Parameters<BridgeSingleton['handleConnect']>[0];
+type BridgeGatewayHandlerResult = Awaited<ReturnType<BridgeSingleton['handleConnect']>>;
+type BridgeSingletonWithState = BridgeSingleton;
+
+type RegisterMeta = {
+  service?: boolean;
+  channel?: boolean;
+  methods?: Set<string>;
+  apiInstanceId?: string;
+  registryFingerprint?: string;
+  registrationMode?: string;
+};
+
+type GlobalRegisterTrace = {
+  lastApiInstanceId?: string;
+  lastRegistryFingerprint?: string;
+  seenRegistryFingerprints: Set<string>;
+  seenApiInstanceIds: Set<string>;
+};
+
+type OpenClawPluginApiWithMeta = OpenClawPluginApi & {
+  [registerMetaSymbol]?: RegisterMeta;
+};
+
+type BncrGatewayRuntime = {
+  currentBridge?: BridgeSingletonWithState;
+  registeredMethodsByRegistry: Map<string, Set<BncrGatewayMethodName>>;
+  serviceRegistered?: boolean;
+  channelRegistered?: boolean;
+  serviceOwnerApiInstanceId?: string;
+  channelOwnerApiInstanceId?: string;
+};
+
+const registerMetaSymbol = Symbol.for('bncr.register.meta');
+const globalRegisterTraceSymbol = Symbol.for('bncr.global.register.trace');
+const bridgeOwnerSymbol = Symbol.for('bncr.bridge.owner');
+const gatewayRuntimeSymbol = Symbol.for('bncr.gateway.runtime');
+const moduleEpoch = `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+const identityIds = new WeakMap<object, string>();
+let identitySeq = 0;
+
+const getIdentityId = (obj: object, prefix: string) => {
+  const existing = identityIds.get(obj);
+  if (existing) return existing;
+  const next = `${prefix}_${moduleEpoch}_${++identitySeq}`;
+  identityIds.set(obj, next);
+  return next;
+};
+
+const getRegistryFingerprint = (api: OpenClawPluginApi) => {
+  const serviceId = getIdentityId(api.registerService as object, 'svc');
+  const channelId = getIdentityId(api.registerChannel as object, 'chn');
+  const methodId = getIdentityId(api.registerGatewayMethod as object, 'mth');
+  return `${serviceId}:${channelId}:${methodId}`;
+};
+
+const getProcessStore = () => {
+  const p = process as NodeJS.Process & {
+    [globalRegisterTraceSymbol]?: GlobalRegisterTrace;
+    [gatewayRuntimeSymbol]?: BncrGatewayRuntime;
+  };
+  return p;
+};
+
+export function createBncrRegisterRuntime() {
+  const gatewayMethodDispatchers: Record<
+    BncrGatewayMethodName,
+    (
+      bridge: BridgeSingletonWithState,
+      opts: BridgeGatewayHandlerContext,
+    ) => BridgeGatewayHandlerResult
+  > = {
+    'bncr.connect': (bridge, opts) => bridge.handleConnect(opts),
+    'bncr.inbound': (bridge, opts) => bridge.handleInbound(opts),
+    'bncr.activity': (bridge, opts) => bridge.handleActivity(opts),
+    'bncr.ack': (bridge, opts) => bridge.handleAck(opts),
+    'bncr.diagnostics': (bridge, opts) => bridge.handleDiagnostics(opts),
+    'bncr.deadLetter.inspect': (bridge, opts) => bridge.handleDeadLetterInspect(opts),
+    'bncr.deadLetter.prune': (bridge, opts) => bridge.handleDeadLetterPrune(opts),
+    'bncr.file.init': (bridge, opts) => bridge.handleFileInit(opts),
+    'bncr.file.chunk': (bridge, opts) => bridge.handleFileChunk(opts),
+    'bncr.file.complete': (bridge, opts) => bridge.handleFileComplete(opts),
+    'bncr.file.abort': (bridge, opts) => bridge.handleFileAbort(opts),
+    'bncr.file.ack': (bridge, opts) => bridge.handleFileAck(opts),
+  };
+
+  const getRegisterMeta = (api: OpenClawPluginApi): RegisterMeta => {
+    const host = api as OpenClawPluginApiWithMeta;
+    if (!host[registerMetaSymbol]) {
+      host[registerMetaSymbol] = { methods: new Set<string>() };
+    }
+    if (!host[registerMetaSymbol]!.methods) {
+      host[registerMetaSymbol]!.methods = new Set<string>();
+    }
+    if (!host[registerMetaSymbol]!.apiInstanceId) {
+      host[registerMetaSymbol]!.apiInstanceId = getIdentityId(api as object, 'api');
+    }
+    if (!host[registerMetaSymbol]!.registryFingerprint) {
+      host[registerMetaSymbol]!.registryFingerprint = getRegistryFingerprint(api);
+    }
+    return host[registerMetaSymbol]!;
+  };
+
+  const getGlobalRegisterTrace = () => {
+    const p = getProcessStore();
+    if (!p[globalRegisterTraceSymbol]) {
+      p[globalRegisterTraceSymbol] = {
+        seenRegistryFingerprints: new Set<string>(),
+        seenApiInstanceIds: new Set<string>(),
+      };
+    }
+    return p[globalRegisterTraceSymbol]!;
+  };
+
+  const getGatewayRuntime = (): BncrGatewayRuntime => {
+    const p = getProcessStore();
+    if (!p[gatewayRuntimeSymbol]) {
+      p[gatewayRuntimeSymbol] = {
+        registeredMethodsByRegistry: new Map<string, Set<BncrGatewayMethodName>>(),
+        serviceRegistered: false,
+        channelRegistered: false,
+      };
+    }
+    return p[gatewayRuntimeSymbol]!;
+  };
+
+  const getBridgeRegisterStateCarrier = (bridge: BridgeSingleton): BridgeRegisterStateCarrier =>
+    bridge as unknown as BridgeRegisterStateCarrier;
+
+  const gatewayMethodRegistry = createBncrGatewayMethodRegistry({
+    getRegisterMeta,
+    getRegistryFingerprint,
+    getGatewayRuntime,
+    gatewayMethodDispatchers,
+    getBridgeRegisterStateCarrier,
+  });
+
+  const getBridgeOwner = (api: OpenClawPluginApi, loaded: LoadedRuntime): BridgeOwner => {
+    const meta = getRegisterMeta(api);
+    return {
+      moduleEpoch,
+      bridgeFactoryId: getIdentityId(loaded.createBncrBridge as object, 'bridgeFactory'),
+      apiInstanceId: meta.apiInstanceId || 'unknown',
+      registryFingerprint: meta.registryFingerprint || 'unknown',
+      registrationMode: meta.registrationMode,
+    };
+  };
+
+  const bridgeSingletonManager = createBncrBridgeSingletonManager({
+    bridgeOwnerSymbol,
+    pluginRoot,
+    pluginFile,
+    loadBncrRuntimeSync,
+    getBridgeOwner,
+  });
+
+  const getCurrentBridge = (): BridgeSingletonWithState => {
+    const bridge = getGatewayRuntime().currentBridge;
+    if (!bridge) throw new Error('bncr current bridge unavailable');
+    return bridge;
+  };
+
+  return {
+    getRegisterMeta,
+    getGlobalRegisterTrace,
+    getGatewayRuntime,
+    shouldAdoptProcessOwner: (apiInstanceId: string, gatewayRuntime: BncrGatewayRuntime) =>
+      shouldAdoptProcessOwner({
+        apiInstanceId,
+        serviceRegistered: gatewayRuntime.serviceRegistered,
+        channelRegistered: gatewayRuntime.channelRegistered,
+        serviceOwnerApiInstanceId: gatewayRuntime.serviceOwnerApiInstanceId,
+        channelOwnerApiInstanceId: gatewayRuntime.channelOwnerApiInstanceId,
+      }),
+    ensureGatewayMethodRegistered: gatewayMethodRegistry.ensureGatewayMethodRegistered,
+    getBridgeSingleton: bridgeSingletonManager.getBridgeSingleton,
+    getBridgeOwnerFromBridge: bridgeSingletonManager.getBridgeOwnerFromBridge,
+    getExistingBridgeSingleton: bridgeSingletonManager.getExistingBridgeSingleton,
+    getCurrentBridge,
+  };
+}