From 5240422f03558260c690d076894b489b234e39a4 Mon Sep 17 00:00:00 2001 From: Shakker Date: Mon, 27 Apr 2026 16:21:56 +0100 Subject: [PATCH] docs: describe plugin metadata snapshot --- docs/plugins/architecture-internals.md | 16 +++++++++------- docs/plugins/architecture.md | 12 ++++++++---- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index 72bd94ce88f..df6a4977e97 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -93,13 +93,15 @@ OpenClaw keeps short in-process caches for: These caches reduce bursty startup and repeated command overhead. They are safe to think of as short-lived performance caches, not persistence. -Gateway hot paths should prefer the current `PluginLookUpTable` or an explicit -manifest registry passed through the call chain. For callers that still rebuild -manifest metadata from the persisted installed plugin index, OpenClaw also keeps -a small bounded fallback cache keyed by the installed index, request shape, -config policy, runtime roots, and manifest/package file signatures. That cache is -only a fallback for repeated installed-index reconstruction; it is not a mutable -runtime plugin registry. +Gateway startup hot paths should prefer the current `PluginMetadataSnapshot`, +the derived `PluginLookUpTable`, or an explicit manifest registry passed through +the call chain. Config validation, startup auto-enable, and plugin bootstrap use +the same snapshot when available. For callers that still rebuild manifest +metadata from the persisted installed plugin index, OpenClaw also keeps a small +bounded fallback cache keyed by the installed index, request shape, config +policy, runtime roots, and manifest/package file signatures. That cache is only a +fallback for repeated installed-index reconstruction; it is not a mutable runtime +plugin registry. Performance note: diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md index 13354c30865..21969c4a30f 100644 --- a/docs/plugins/architecture.md +++ b/docs/plugins/architecture.md @@ -145,19 +145,23 @@ The important design boundary: That split lets OpenClaw validate config, explain missing/disabled plugins, and build UI/schema hints before the full runtime is active. -### Plugin lookup table +### Plugin metadata snapshot and lookup table -Gateway startup builds a `PluginLookUpTable` from the installed plugin index and manifest registry for the current config snapshot. The table is metadata-only: it stores plugin ids, manifest records, diagnostics, owner maps, a plugin id normalizer, and the startup plugin plan. It does not hold loaded plugin modules, provider SDKs, package contents, or runtime exports. +Gateway startup builds one `PluginMetadataSnapshot` for the current config snapshot. The snapshot is metadata-only: it stores the installed plugin index, manifest registry, manifest diagnostics, owner maps, a plugin id normalizer, and manifest records. It does not hold loaded plugin modules, provider SDKs, package contents, or runtime exports. -The lookup table keeps repeated startup decisions on the fast path: +Plugin-aware config validation, startup auto-enable, and Gateway plugin bootstrap consume that snapshot instead of rebuilding manifest/index metadata independently. `PluginLookUpTable` is derived from the same snapshot and adds the startup plugin plan for the current runtime config. + +The snapshot and lookup table keep repeated startup decisions on the fast path: - channel ownership - deferred channel startup - startup plugin ids - provider and CLI backend ownership - setup provider, command alias, model catalog provider, and manifest contract ownership +- plugin config schema and channel config schema validation +- startup auto-enable decisions -The safety boundary is snapshot replacement, not mutation. Rebuild the table when config, plugin inventory, install records, or persisted index policy changes. Do not treat it as a broad mutable global registry, and do not keep unbounded historical tables. Runtime plugin loading remains separate from lookup-table metadata so stale runtime state cannot be hidden behind a metadata cache. +The safety boundary is snapshot replacement, not mutation. Rebuild the snapshot when config, plugin inventory, install records, or persisted index policy changes. Do not treat it as a broad mutable global registry, and do not keep unbounded historical snapshots. Runtime plugin loading remains separate from metadata snapshots so stale runtime state cannot be hidden behind a metadata cache. Some cold-path callers still reconstruct manifest registries directly from the persisted installed plugin index instead of receiving a Gateway `PluginLookUpTable`. That fallback path keeps a small bounded in-memory cache keyed by the installed index, request shape, config policy, runtime roots, and manifest/package file signatures. It is a fallback safety net for repeated index reconstruction, not the preferred Gateway hot path. Prefer passing the current lookup table or an explicit manifest registry through runtime flows when a caller already has one.