feat!: migrate Role Manager to operator profile runtime (#96)

* feat(role-manager): adopt capability-adapters runtime architecture

Migrate from monolithic ContractAdapter to profile-based EcosystemRuntime:

- Replace AdapterProvider with RuntimeProvider, getAdapter with getRuntime
- Introduce RoleManagerRuntime (OperatorEcosystemRuntime + relayer) and
  RoleManagerAdapter compatibility shim for incremental hook migration
- Add legacyOperatorRuntime bridge for adapters still on createAdapter
- Migrate WalletSyncProvider to activeRuntime API with ecosystem-scoped
  wallet session support and simplified chain switch logic
- Update all hooks/tests from ContractAdapter to RoleManagerAdapter types
- Remove broken contract-adapter-compat.d.ts

* chore(role-manager): temporary legacy support

* feat(role-manager): remove legacy operator runtime and map adapter-evm-core locally

Require createRuntime for operator profile.

Extend pnpmfile for adapter-evm-core local dev.

* feat(role-manager): add runtime disposal lifecycle to useNetworkAdapter

Apply the same promote-then-dispose handoff pattern from the shared
RuntimeProvider/WalletStateProvider layer to the app-local runtime
path. Superseded runtimes are disposed after their replacement is
promoted to state, cancelled loads are disposed immediately, and the
active runtime is disposed on unmount. Disposal is deferred via
setTimeout to avoid RuntimeDisposedError in React's dev-mode commit
phase. Updates tests to assert correct disposal behavior.

* refactor(role-manager): remove RoleManagerAdapter compatibility layer

Migrate all production code and tests from the flattened
RoleManagerAdapter interface to capability-qualified
RoleManagerRuntime access (runtime.addressing, runtime.explorer,
runtime.accessControl, runtime.query, runtime.contractLoading,
runtime.relayer). Remove toRoleManagerAdapter(), getAdapter(),
getAccessControlService(), and the dual-path fallback in
useAccessControlService / useContractRegistration.

* chore(deps): regenerate lockfile without local dev tarball paths

* chore(deps): update @OpenZeppelin/ui-* to latest published versions

* feat(deps): bump @OpenZeppelin/ui-* deps to ^2.0.0

* fix(role-manager): suppress exhaustive-deps for intentional ID-only tracking

* feat(ci): add RC adapter resolution for staging builds (#97)

Port the RC adapter resolution mechanism from ui-builder so staging
Docker builds can consume pre-release adapter packages.

- Add scripts/resolve-staging-adapters.cjs that queries npm for "rc"
  and "latest" dist-tags, picks the newer version, and runs a surgical
  pnpm add --save-exact for adapter packages only.
- Update Dockerfile with ADAPTER_DIST_TAG build arg and resolution step
  between frozen-lockfile install and build.
- Pass ADAPTER_DIST_TAG=rc in the staging workflow build-args.

* feat(deps): bump adapter packages to ^2.0.0 with pre-release resolution

Bump all @openzeppelin/adapter-* and adapters-vite dependencies to
^2.0.0 for the capability adapters migration.

Extend .pnpmfile.cjs to widen adapter caret ranges to include
pre-release versions during resolution, so pnpm can resolve to RC
packages when the stable version hasn't shipped yet. Once stable
2.0.0 is published, pnpm naturally resolves to it instead.

* fix(role-manager): align test mocks and component with v2 runtime API

- WalletSyncProvider: read activeRuntime/isRuntimeLoading, pass wallet +
  networkCatalog as separate props to NetworkSwitchManager, skip chain
  switch on initial sync and cross-ecosystem switches
- Nest getExplorerUrl/getExplorerTxUrl under runtime.explorer in mocks
- Update error assertions from "runtime" to "adapter" wording
- Fix fake timer cascading timeouts in useNetworkAdapter tests

* fix(role-manager): address PR review feedback

- Use Object.create instead of spread in attachRelayerCapability to
  preserve runtime proxy behavior and object identity
- Use execFileSync in resolve-staging-adapters to prevent shell injection
- Include @openzeppelin/adapters-vite in prerelease version widening
- Update stale adapter terminology in comments, variables, JSDoc, and
  user-facing copy to use runtime language

* fix(role-manager): update lockfile pnpmfileChecksum

The previous commit modified .pnpmfile.cjs without updating the
lockfile checksum, causing CI to fail with
ERR_PNPM_LOCKFILE_CONFIG_MISMATCH on --frozen-lockfile.

* fix(role-manager): address second round of PR review feedback

- Use execFileSync for pnpm add in resolve-staging-adapters to eliminate
  remaining shell injection vector; remove unused execSync import
- Dispose runtime immediately after extracting addressing capability in
  AddressBook.resolveAddressing to prevent resource leaks
- Dispose previous promoted runtime on getRuntime error path in
  useNetworkAdapter so stale connections don't persist
- Update Dockerfile comment to reflect that .pnpmfile.cjs now also runs
  the prerelease-widening hook (not purely a no-op in Docker)

* fix(role-manager): update stale adapter terminology in JSDoc and comments

- useContractSchema: @param now says "runtime" instead of "adapter"
- useExpirationMetadata: file-level JSDoc updated to reference runtime's
  accessControl capability instead of "adapter.getExpirationMetadata()"
- AddContractDialog: inline comment updated to "Runtime for schema loading"

* fix(role-manager): harden parseSemver in resolve-staging-adapters

Strip build metadata (+...) before parsing and validate that
major/minor/patch are finite numbers to avoid silent NaN comparisons.

* fix(role-manager): update stale adapter terminology and harden pickBestVersion

- useExpirationMetadata guard comment now references runtime/accessControl
- App.tsx provider-hierarchy comment updated to "runtime session"
- pickBestVersion only prefers latest over rc when latest is a stable
  (non-prerelease) release, preventing incorrect downgrades

* fix(role-manager): correct caret upper bound for 0.x ranges in pnpmfile

allowAdapterPrereleases now computes the caret ceiling correctly for
major-zero ranges (^0.3.0 -> <0.4.0 instead of <1.0.0), matching
npm/pnpm caret semantics and preventing unintended major upgrades.

Author: pasevin

.github/workflows/docker-stg.yaml

@@ -214,6 +214,7 @@ jobs:
           build-args: |
             VITE_APP_CFG_FEATURE_FLAG_ANALYTICS_ENABLED=true
             VITE_GA_TAG_ID=${{ secrets.VITE_GA_TAG_ID_STAGING }}
+            ADAPTER_DIST_TAG=rc
           secrets: |
             etherscan_api_key=${{ secrets.VITE_APP_CFG_SERVICE_ETHERSCANV2_API_KEY }}
             routescan_api_key=${{ secrets.VITE_APP_CFG_SERVICE_ROUTESCAN_API_KEY }}

.pnpmfile.cjs

@@ -33,6 +33,8 @@ const STANDARD_FAMILIES = {
     defaultPath: '../openzeppelin-adapters',
     packageMap: {
       '@openzeppelin/adapters-vite': 'packages/adapters-vite',
+      '@openzeppelin/adapter-runtime-utils': 'packages/adapter-runtime-utils',
+      '@openzeppelin/adapter-evm-core': 'packages/adapter-evm-core',
       '@openzeppelin/adapter-evm': 'packages/adapter-evm',
       '@openzeppelin/adapter-midnight': 'packages/adapter-midnight',
       '@openzeppelin/adapter-polkadot': 'packages/adapter-polkadot',
@@ -210,22 +212,53 @@ function rewriteDependencies(pkg, context, cacheDir, familyKey, family) {
   }
 }
 
-function readPackage(pkg, context) {
-  if (!isAnyLocalFamilyEnabled()) {
-    return pkg;
+/**
+ * Widen `^X.Y.Z` ranges on `@openzeppelin/adapter*` packages to also include
+ * pre-release versions (`>=X.Y.Z-0 <(X+1).0.0`).
+ *
+ * This lets `pnpm install` resolve RC packages (e.g. 2.0.0-rc.1) when the
+ * stable version (e.g. 2.0.0) hasn't been published yet, without changing
+ * the declared range in package.json. Once the stable version ships, pnpm
+ * naturally resolves to it (highest match wins). The rewrite is harmless
+ * when stable versions are available — it's effectively a permanent no-op.
+ *
+ * Skips deps already rewritten to `file:` paths by local-dev mode.
+ */
+function allowAdapterPrereleases(pkg) {
+  for (const depType of ['dependencies', 'devDependencies']) {
+    if (!pkg[depType]) continue;
+    for (const [name, range] of Object.entries(pkg[depType])) {
+      if (!name.startsWith('@openzeppelin/adapter') && !name.startsWith('@openzeppelin/adapters-'))
+        continue;
+      const m = range.match(/^\^(\d+)\.(\d+)\.(\d+)$/);
+      if (!m) continue;
+      const maj = Number(m[1]), min = Number(m[2]), pat = Number(m[3]);
+      const upper = maj > 0
+        ? `${maj + 1}.0.0`
+        : min > 0
+          ? `0.${min + 1}.0`
+          : `0.0.${pat + 1}`;
+      pkg[depType][name] = `>=${maj}.${min}.${pat}-0 <${upper}`;
+    }
   }
+}
 
-  const workspaceRoot = __dirname;
-  const projectConfig = readProjectConfig(workspaceRoot);
+function readPackage(pkg, context) {
+  if (isAnyLocalFamilyEnabled()) {
+    const workspaceRoot = __dirname;
+    const projectConfig = readProjectConfig(workspaceRoot);
 
-  for (const [familyKey, family] of Object.entries(projectConfig.families)) {
-    if (process.env[family.envFlag] !== 'true') {
-      continue;
-    }
+    for (const [familyKey, family] of Object.entries(projectConfig.families)) {
+      if (process.env[family.envFlag] !== 'true') {
+        continue;
+      }
 
-    rewriteDependencies(pkg, context, projectConfig.cacheDir, familyKey, family);
+      rewriteDependencies(pkg, context, projectConfig.cacheDir, familyKey, family);
+    }
   }
 
+  allowAdapterPrereleases(pkg);
+
   return pkg;
 }
 

Dockerfile

@@ -28,19 +28,32 @@ RUN rm -rf /root/.cache/node-gyp /root/.npm /root/.node-gyp || true
 RUN npm install -g pnpm
 
 # Copy workspace configuration files
-# Note: .pnpmfile.cjs is included because pnpm-lock.yaml has a checksum for it
-# The hook is a no-op in Docker (LOCAL_UI env var is not set)
+# Note: .pnpmfile.cjs is included because pnpm-lock.yaml has a checksum for it.
+# The local-dev rewrite hook is a no-op in Docker (LOCAL_* env vars are not set),
+# but the prerelease-widening hook (allowAdapterPrereleases) always runs.
 COPY ./package.json ./pnpm-lock.yaml ./pnpm-workspace.yaml ./.npmrc ./.pnpmfile.cjs ./
 COPY ./tsconfig.json ./tsconfig.base.json ./tsconfig.node.json ./
 
-# Copy all workspace packages and apps
+# Copy all workspace packages, apps, and scripts
 COPY ./packages ./packages/
 COPY ./apps ./apps/
+COPY ./scripts ./scripts/
 
-# Install dependencies directly from the public npm registry
+# Step 1: Install dependencies from frozen lockfile (exact production dependency tree)
 # Retry once on failure after clearing possible corrupted caches to avoid node-gyp issues
 RUN pnpm install --frozen-lockfile || (echo "Install failed, clearing caches and retrying..." && rm -rf /root/.cache/node-gyp /root/.npm /root/.node-gyp && pnpm install --frozen-lockfile)
 
+# Step 2: Surgically override adapter packages for staging builds.
+# When ADAPTER_DIST_TAG is set (e.g. "rc"), the resolution script queries npm for
+# both the requested dist-tag and "latest", picks the newer version per adapter, and
+# runs `pnpm add --save-exact` for only those packages. All non-adapter dependencies
+# remain byte-for-byte identical to the frozen lockfile from Step 1.
+# When ADAPTER_DIST_TAG is unset (production), this step is a no-op.
+ARG ADAPTER_DIST_TAG
+RUN if [ -n "$ADAPTER_DIST_TAG" ]; then \
+      node scripts/resolve-staging-adapters.cjs "$ADAPTER_DIST_TAG"; \
+    fi
+
 # Set Node.js memory limit to prevent OOM during build
 # This is especially important for TypeScript compilation in CI environments
 ENV NODE_OPTIONS="--max-old-space-size=4096"

apps/role-manager/package.json

@@ -18,24 +18,24 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@openzeppelin/adapter-evm": "^1.1.0",
-    "@openzeppelin/adapter-polkadot": "^1.1.0",
-    "@openzeppelin/adapter-stellar": "^1.1.0",
-    "@openzeppelin/ui-components": "^1.7.0",
-    "@openzeppelin/ui-react": "^1.2.0",
-    "@openzeppelin/ui-renderer": "^1.2.0",
+    "@openzeppelin/adapter-evm": "^2.0.0",
+    "@openzeppelin/adapter-polkadot": "^2.0.0",
+    "@openzeppelin/adapter-stellar": "^2.0.0",
+    "@openzeppelin/ui-components": "^2.0.0",
+    "@openzeppelin/ui-react": "^2.0.0",
+    "@openzeppelin/ui-renderer": "^2.0.0",
     "@openzeppelin/ui-storage": "^1.2.0",
     "@openzeppelin/ui-styles": "^1.0.0",
-    "@openzeppelin/ui-types": "^1.13.0",
-    "@openzeppelin/ui-utils": "^1.4.0",
+    "@openzeppelin/ui-types": "^2.0.0",
+    "@openzeppelin/ui-utils": "^2.0.0",
     "lucide-react": "^0.555.0",
     "pluralize": "^8.0.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router-dom": "^7.1.1"
   },
   "devDependencies": {
-    "@openzeppelin/adapters-vite": "^1.3.2",
+    "@openzeppelin/adapters-vite": "^2.0.0",
     "@tailwindcss/vite": "^4.2.1",
     "@types/pluralize": "^0.0.33",
     "@types/react": "^19.2.8",

apps/role-manager/src/App.tsx

@@ -7,7 +7,7 @@ import {
   Toaster,
   TooltipProvider,
 } from '@openzeppelin/ui-components';
-import { AdapterProvider, AnalyticsProvider, WalletStateProvider } from '@openzeppelin/ui-react';
+import { AnalyticsProvider, RuntimeProvider, WalletStateProvider } from '@openzeppelin/ui-react';
 import type { NativeConfigLoader } from '@openzeppelin/ui-types';
 
 import { TrackedRoute } from './components/Analytics';
@@ -16,7 +16,7 @@ import { AliasLabelBridge } from './context/AliasLabelBridge';
 import { BlockTimeProvider } from './context/BlockTimeContext';
 import { ContractProvider } from './context/ContractContext';
 import { WalletSyncProvider } from './context/WalletSyncProvider';
-import { getAdapter, getNetworkById } from './core/ecosystems/ecosystemManager';
+import { getNetworkById, getRuntime } from './core/ecosystems/ecosystemManager';
 import { AddressBook } from './pages/AddressBook';
 import { AuthorizedAccounts } from './pages/AuthorizedAccounts';
 import { Dashboard } from './pages/Dashboard';
@@ -62,26 +62,24 @@ function createQueryClient(): QueryClient {
  * - BrowserRouter: Client-side routing
  * - NetworkErrorNotificationProvider: Error notifications with "Configure" action buttons
  * - AnalyticsProvider: Google Analytics tracking (Feature: analytics)
- * - AdapterProvider: Manages adapter singleton instances
+ * - RuntimeProvider: Manages runtime singleton instances
  * - ContractProvider: Shared contract selection state (OUTSIDE WalletStateProvider)
  * - AliasLabelBridge: Bridges alias storage → AddressLabelProvider (auto-labels all AddressDisplay)
  * - WalletStateProvider: Manages wallet connection state
  * - WalletSyncProvider: Syncs ContractContext network → WalletStateProvider + handles EVM chain switches
  *
  * IMPORTANT: ContractProvider must be OUTSIDE WalletStateProvider because
- * WalletStateProvider uses a dynamic key for its internal UI context provider.
- * When the key changes (adapter loads), React remounts children. If ContractProvider
- * were inside, it would remount and reset selectedNetwork to null, causing an
- * infinite loop: network selected → adapter loads → provider remounts → network
- * resets to null → network selected again...
+ * WalletStateProvider remounts its internal wallet UI provider when the active
+ * ecosystem session changes. If ContractProvider were inside, a cross-ecosystem
+ * switch could remount it and reset selectedNetwork to null, causing a loop.
  *
  * WalletSyncProvider syncs the selected network from ContractContext to
- * WalletStateProvider, enabling the wallet UI to load the correct adapter.
+ * WalletStateProvider, enabling the wallet UI to load the correct runtime session.
  * It also handles EVM chain switching - when users switch between EVM networks,
- * it triggers the wallet's chain switch prompt instead of disconnecting.
+ * it triggers the wallet's chain switch prompt instead of resetting the wallet session.
  *
  * Feature: 007-dashboard-real-data
- * Feature: 013-wallet-connect-header (AdapterProvider, WalletStateProvider, WalletSyncProvider)
+ * Feature: 013-wallet-connect-header (RuntimeProvider, WalletStateProvider, WalletSyncProvider)
  * Feature: network-settings (NetworkErrorNotificationProvider)
  */
 function App() {
@@ -124,7 +122,7 @@ function App() {
         <NetworkErrorNotificationProvider>
           <TooltipProvider delayDuration={300}>
             <AnalyticsProvider tagId={analyticsTagId} autoInit>
-              <AdapterProvider resolveAdapter={getAdapter}>
+              <RuntimeProvider resolveRuntime={getRuntime}>
                 <ContractProvider>
                   <AliasLabelBridge>
                     <BlockTimeProvider>
@@ -183,7 +181,7 @@ function App() {
                     </BlockTimeProvider>
                   </AliasLabelBridge>
                 </ContractProvider>
-              </AdapterProvider>
+              </RuntimeProvider>
             </AnalyticsProvider>
             <Toaster position="top-right" />
           </TooltipProvider>

apps/role-manager/src/components/Admin/TransferAdminDialog.tsx

@@ -137,7 +137,7 @@ export function TransferAdminDialog({
   });
 
   // Get adapter for address validation
-  const { adapter, isAdapterLoading } = useSelectedContract();
+  const { runtime, isRuntimeLoading } = useSelectedContract();
 
   // React Hook Form setup
   const form = useForm<TransferAdminFormData>({
@@ -270,10 +270,10 @@ export function TransferAdminDialog({
       default:
         return (
           <TransferAdminFormContent
-            key={adapter ? 'with-adapter' : 'no-adapter'}
+            key={runtime ? 'with-runtime' : 'no-runtime'}
             form={form}
-            adapter={adapter}
-            isAdapterLoading={isAdapterLoading}
+            runtime={runtime}
+            isRuntimeLoading={isRuntimeLoading}
             isWalletConnected={isWalletConnected}
             requiresExpiration={requiresExpiration}
             currentBlock={currentBlock}
@@ -325,8 +325,8 @@ export function TransferAdminDialog({
 
 interface TransferAdminFormContentProps {
   form: ReturnType<typeof useForm<TransferAdminFormData>>;
-  adapter: ReturnType<typeof useSelectedContract>['adapter'];
-  isAdapterLoading: boolean;
+  runtime: ReturnType<typeof useSelectedContract>['runtime'];
+  isRuntimeLoading: boolean;
   isWalletConnected: boolean;
   /** Whether expiration input is required (adapter says mode: 'required') */
   requiresExpiration: boolean;
@@ -341,8 +341,8 @@ interface TransferAdminFormContentProps {
 
 function TransferAdminFormContent({
   form,
-  adapter,
-  isAdapterLoading,
+  runtime,
+  isRuntimeLoading,
   isWalletConnected,
   requiresExpiration,
   currentBlock,
@@ -395,8 +395,8 @@ function TransferAdminFormContent({
   const canSubmit =
     isValid &&
     !isSubmitting &&
-    !isAdapterLoading &&
-    adapter !== null &&
+    !isRuntimeLoading &&
+    runtime !== null &&
     isWalletConnected &&
     !expirationError;
 
@@ -422,13 +422,13 @@ function TransferAdminFormContent({
           name="newAdminAddress"
           label="New Admin Address"
           placeholder={
-            adapter
-              ? (getEcosystemMetadata(adapter.networkConfig.ecosystem)?.addressExample ?? '0x...')
+            runtime
+              ? (getEcosystemMetadata(runtime.networkConfig.ecosystem)?.addressExample ?? '0x...')
               : '0x...'
           }
           helperText="The address that will become the new admin of this contract."
           control={control}
-          adapter={adapter ?? undefined}
+          addressing={runtime?.addressing ?? undefined}
           validation={{ required: true }}
         />
       </div>
@@ -502,7 +502,7 @@ function TransferAdminFormContent({
           Cancel
         </Button>
         <Button type="submit" disabled={!canSubmit} aria-label="Transfer admin role to new address">
-          {isAdapterLoading ? 'Loading...' : 'Transfer Admin'}
+          {isRuntimeLoading ? 'Loading...' : 'Transfer Admin'}
         </Button>
       </DialogFooter>
     </form>

apps/role-manager/src/components/Contracts/AddContractDialog.tsx

@@ -97,16 +97,16 @@ export function AddContractDialog({
   // Alias storage for auto-creating alias when a contract is added
   const { save: saveAlias } = useAliasStorage();
 
-  // Network adapter for schema loading (set after form submission)
+  // Runtime for schema loading (set after form submission)
   const [selectedNetwork, setSelectedNetwork] = useState<NetworkConfig | null>(null);
-  const { adapter, isLoading: isAdapterLoading } = useNetworkAdapter(selectedNetwork);
+  const { runtime, isLoading: isRuntimeLoading } = useNetworkAdapter(selectedNetwork);
 
   // Schema loader hook
-  const schemaLoader = useContractSchemaLoader(adapter);
+  const schemaLoader = useContractSchemaLoader(runtime);
 
   // Access control service for capability detection
   const { service: accessControlService, isReady: isAccessControlReady } =
-    useAccessControlService(adapter);
+    useAccessControlService(runtime);
 
   /**
    * Reset all dialog state to initial values
@@ -153,7 +153,7 @@ export function AddContractDialog({
    * Actually load the schema once adapter is ready
    */
   const loadSchema = useCallback(async (): Promise<SchemaLoadResult | null> => {
-    if (!adapter || !pendingFormData) {
+    if (!runtime || !pendingFormData) {
       return null;
     }
 
@@ -162,7 +162,7 @@ export function AddContractDialog({
     };
 
     return schemaLoader.load(pendingFormData.address, artifacts);
-  }, [adapter, pendingFormData, schemaLoader]);
+  }, [runtime, pendingFormData, schemaLoader]);
 
   /**
    * Save contract with schema and capabilities to storage,
@@ -286,14 +286,14 @@ export function AddContractDialog({
   useEffect(() => {
     if (
       step === 'loading-schema' &&
-      adapter &&
-      !isAdapterLoading &&
+      runtime &&
+      !isRuntimeLoading &&
       isAccessControlReady &&
       !loadStartedRef.current
     ) {
       executeLoadAndSave();
     }
-  }, [step, adapter, isAdapterLoading, isAccessControlReady, executeLoadAndSave]);
+  }, [step, runtime, isRuntimeLoading, isAccessControlReady, executeLoadAndSave]);
 
   /**
    * Handle retry after error
@@ -324,7 +324,7 @@ export function AddContractDialog({
 
   // Get explorer URL for the contract address
   const explorerUrl =
-    adapter && pendingFormData ? adapter.getExplorerUrl(pendingFormData.address) : null;
+    runtime && pendingFormData ? runtime.explorer.getExplorerUrl(pendingFormData.address) : null;
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>