PR #62330: fix(matrix): harden lazy local runtime loading

• Repository: openclaw/openclaw
• Author: gumadeiras
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/62330

Description (problem / solution / changelog)

Summary

• add a shared alias-safe plugin-local lazy loader for bundled plugin runtime modules
• move Matrix lazy local runtime imports onto that shared seam across auth, bootstrap, send, monitor, and runtime entry paths
• add nested-package regression coverage plus plugin-sdk/docs updates for the new lazy-runtime helper

Why

This branch hardens the source-tree / nested-package runtime seam that showed up in the Matrix Docker reports (#62170, #62260).

The root issue is not Matrix auth logic itself; it is raw lazy import("./...") hops inside a bundled plugin package whose lazily loaded modules import openclaw/plugin-sdk/*. In nested package roots, that can fall off the alias-aware loader seam and fail with Cannot find package 'openclaw'.

PR #62316 should address the official Docker runtime path by restoring packaged dist/extensions resolution. This draft keeps the broader source-runtime seam fix separate so we can decide whether we want the extra hardening or just the Docker fix.

Scope boundary

• no repo-wide plugin migration
• no Dockerfile changes here
• Matrix only, plus the shared helper needed to avoid repeating Matrix-specific runtime shims

Testing

• pnpm build
• OPENCLAW_LOCAL_CHECK=0 pnpm test extensions/matrix/src/plugin-entry.runtime.test.ts extensions/matrix/src/matrix/client.test.ts extensions/matrix/src/matrix/client-bootstrap.test.ts extensions/matrix/src/matrix/send/client.test.ts
• OPENCLAW_LOCAL_CHECK=0 pnpm test src/plugin-sdk/lazy-runtime.test.ts
• OPENCLAW_LOCAL_CHECK=0 pnpm test src/plugins/contracts/runtime-seams.contract.test.ts -t "allows activated runtime facades when the resolved plugin root matches an installed-style manifest record"

Notes

• src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts still reports pre-existing extension import leaks in Discord/Slack/Telegram doctor-contract files; not introduced by this branch.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/plugins/architecture.md (modified, +3/-0)
• docs/plugins/sdk-migration.md (modified, +1/-1)
• docs/plugins/sdk-overview.md (modified, +1/-1)
• extensions/matrix/index.ts (modified, +9/-4)
• extensions/matrix/src/actions.ts (modified, +5/-1)
• extensions/matrix/src/channel.ts (modified, +12/-3)
• extensions/matrix/src/cli-metadata.ts (modified, +7/-1)
• extensions/matrix/src/cli.ts (modified, +5/-1)
• extensions/matrix/src/legacy-crypto.ts (modified, +5/-1)
• extensions/matrix/src/matrix/client-bootstrap.ts (modified, +22/-7)
• extensions/matrix/src/matrix/client/config.ts (modified, +32/-18)
• extensions/matrix/src/matrix/client/create-client.ts (modified, +23/-7)
• extensions/matrix/src/matrix/client/shared.ts (modified, +5/-1)
• extensions/matrix/src/matrix/client/storage.ts (modified, +5/-1)
• extensions/matrix/src/matrix/credentials-write.runtime.ts (modified, +9/-3)
• extensions/matrix/src/matrix/monitor/startup.ts (modified, +22/-5)
• extensions/matrix/src/matrix/monitor/verification-events.ts (modified, +10/-2)
• extensions/matrix/src/matrix/probe.ts (modified, +5/-1)
• extensions/matrix/src/matrix/sdk.ts (modified, +5/-1)
• extensions/matrix/src/matrix/sdk/crypto-facade.ts (modified, +5/-1)
• extensions/matrix/src/matrix/send/client.ts (modified, +5/-1)
• extensions/matrix/src/onboarding.ts (modified, +5/-1)
• extensions/matrix/src/plugin-entry.runtime.ts (modified, +13/-4)
• extensions/matrix/src/setup-core.ts (modified, +5/-1)
• src/channels/plugins/module-loader.test.ts (modified, +11/-0)
• src/channels/plugins/module-loader.ts (modified, +9/-88)
• src/plugin-sdk/facade-runtime.ts (modified, +8/-3)
• src/plugin-sdk/lazy-runtime.test.ts (added, +71/-0)
• src/plugin-sdk/lazy-runtime.ts (modified, +41/-0)
• src/plugins/contracts/plugin-sdk-subpaths.test.ts (modified, +5/-1)
• src/plugins/local-module-loader.ts (added, +150/-0)