From 5de733fa8018cbd248ea2a42a6febe41df72d6af Mon Sep 17 00:00:00 2001 From: Gustavo Madeira Santana Date: Sun, 15 Mar 2026 14:43:40 +0000 Subject: [PATCH] Docs: refresh extension host migration status --- ...-capability-catalog-and-arbitration-spec.md | 3 ++- ...nclaw-extension-contribution-schema-spec.md | 3 ++- ...claw-extension-host-implementation-guide.md | 12 +++++++----- ...tension-host-lifecycle-and-security-spec.md | 18 ++++++++++-------- .../openclaw-kernel-event-pipeline-spec.md | 2 +- ...aw-kernel-extension-host-transition-plan.md | 12 +++++++----- 6 files changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md b/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md index 6672e52de5f..21fc16c0bf8 100644 --- a/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-capability-catalog-and-arbitration-spec.md @@ -44,7 +44,7 @@ What has been implemented: - loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` - loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` - loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, including explicit compatibility `lifecycleState` mapping +- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values - loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts` - channel, provider, gateway-method, tool, CLI, service, command, context-engine, and hook registration normalization now has a host-owned helper boundary for future catalog migration @@ -56,6 +56,7 @@ How it has been implemented: - by beginning runtime registration migration with host-owned normalization helpers before attempting full canonical catalog publication - by moving cache-key construction and registry cache control behind host-owned helpers before attempting canonical catalog publication - by beginning loader-path migration with host-owned compatibility, candidate-planning, import-flow, policy, runtime, register-flow, candidate-orchestration, top-level load orchestration, record-state with compatibility lifecycle mapping, and finalization helpers before attempting canonical catalog publication +- by converting the compatibility record-state layer into an enforced loader lifecycle state machine before catalog publication work What remains pending: diff --git a/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md b/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md index 8d862584b12..5d4e9a3527f 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-contribution-schema-spec.md @@ -48,7 +48,7 @@ What has been implemented: - loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` - loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` - loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, including explicit compatibility `lifecycleState` mapping +- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values - loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts` How it has been implemented: @@ -60,6 +60,7 @@ How it has been implemented: - by starting runtime contribution migration with normalization helpers that preserve the legacy plugin API surface - by making cache-key construction and registry cache control explicit host-owned seams before changing loader activation-state ownership - by making the first loader compatibility, candidate-planning, import-flow, runtime-decision, register-flow, candidate-orchestration, top-level load orchestration, record-state with compatibility lifecycle mapping, and finalization helpers explicit host-owned seams before introducing a versioned compatibility layer +- by turning the compatibility record-state layer into an enforced loader lifecycle state machine before broadening the schema-driven host lifecycle model What remains pending: diff --git a/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md b/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md index 13317e4aef9..15fc36abb91 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-host-implementation-guide.md @@ -69,7 +69,7 @@ What has been implemented so far: - loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` - loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` - loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, including explicit compatibility `lifecycleState` mapping +- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values - loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts` - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations - several static and lookup consumers now read through the host boundary or resolved-extension model: @@ -99,9 +99,10 @@ How it has been done: - by moving loader runtime decisions behind host-owned helpers while preserving lazy loading, config validation behavior, and memory-slot policy behavior - by moving post-import planning and `register(...)` execution behind host-owned helpers before changing entry-path and import flow - by composing those seams into one host-owned per-candidate orchestrator before changing cache and lifecycle finalization behavior -- by moving loader record-state transitions into host-owned helpers before introducing a full lifecycle state machine +- by moving loader record-state transitions into host-owned helpers before enforcing them as a loader lifecycle state machine - by moving cache writes, provenance warnings, final memory-slot warnings, and activation into a host-owned loader finalizer before introducing an explicit lifecycle state machine -- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before introducing a full lifecycle state machine +- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before enforcing the loader lifecycle state machine +- by turning that compatibility `lifecycleState` field into an enforced loader lifecycle state machine with readiness promotion during finalization - by moving the remaining top-level loader orchestration into a host-owned module so `src/plugins/loader.ts` becomes a compatibility facade instead of the real owner - by moving central readers first, so later lifecycle and compatibility work can land on one boundary instead of many ad hoc call sites - by adding focused tests for each extracted seam before widening the boundary further @@ -118,13 +119,14 @@ Committed implementation slices so far: - `33ef55a9ee` `Plugins: add loader lifecycle state mapping` - `6590e19095` `Plugins: extract loader cache control` - `c8d82a8f19` `Plugins: extract loader orchestration` +- `d32f65eb5e` `Plugins: add loader lifecycle state machine` - `89414ed857` `Docs: track extension host migration internally` - `d8af1eceaf` `Docs: refresh extension host migration status` What is still missing for these phases: - keeping the cutover inventory current as more surfaces move -- the full lifecycle state machine, remaining explicit activation-state ownership, policy gate, and broad host-owned registries described for Phase 2 +- broader lifecycle ownership beyond the loader state machine, remaining explicit activation-state ownership, policy gate, and broad host-owned registries described for Phase 2 - minimal SDK compatibility work beyond preserving current behavior indirectly through existing loading - any pilot migration, event pipeline, canonical catalog, or arbitration implementation @@ -315,7 +317,7 @@ Current implementation status: - the host exposes a resolved-extension registry view for static consumers - plugin skills, plugin auto-enable, and config validation indexing now consume host-owned resolved-extension data - activation, loader cache control, loader policy, loader candidate planning, loader import flow, loader runtime decisions, loader post-import register flow, loader candidate orchestration, loader top-level load orchestration, loader record-state helpers, and loader finalization now route through `src/extension-host/*` -- lifecycle state ownership, activation states, policy evaluation, and broad host-owned registries are still not implemented +- broader lifecycle state ownership beyond the loader state machine, activation states, policy evaluation, and broad host-owned registries are still not implemented ### Phase 3: Build compatibility bridges diff --git a/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md b/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md index e866771cdd5..10dd474f7d3 100644 --- a/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-extension-host-lifecycle-and-security-spec.md @@ -14,7 +14,7 @@ The kernel does not participate in these concerns directly. - [x] Write the initial boundary cutover inventory for every current plugin-owned surface. - [ ] Keep the boundary cutover inventory updated as surfaces move. -- [ ] Implement the extension lifecycle state machine and document the concrete runtime states in code. +- [ ] Extend the loader lifecycle state machine into full extension-host lifecycle ownership and document the concrete runtime states in code. - [ ] Implement advisory versus enforced permission handling exactly as specified here. - [ ] Implement host-owned registries for config, setup, CLI, routes, services, slots, and backends. - [ ] Implement per-extension state ownership and migration from current shared plugin state. @@ -26,7 +26,8 @@ The kernel does not participate in these concerns directly. Current status against this spec: - registry ownership and the first compatibility-preserving loader slices have landed -- lifecycle orchestration, policy gates, and activation-state management have not landed +- a loader-scoped lifecycle state machine has landed +- broader lifecycle orchestration, policy gates, and activation-state management have not landed What has been implemented: @@ -45,8 +46,8 @@ What has been implemented: - loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` - loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` - loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, including explicit compatibility `lifecycleState` mapping -- loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts` +- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values +- loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts`, including readiness promotion for successfully registered plugins How it has been implemented: @@ -65,14 +66,15 @@ How it has been implemented: - by moving loader runtime decisions next while preserving the current lazy-load, config-validation, and memory-slot behavior - by moving post-import planning and `register(...)` execution next while leaving entry-path and import flow unchanged - by composing those seams into one host-owned per-candidate loader orchestrator before moving final lifecycle-state behavior -- by moving the remaining top-level loader orchestration into a host-owned module while leaving the full lifecycle state machine itself unimplemented -- by moving record-state transitions next while leaving the lifecycle state machine itself unimplemented +- by moving the remaining top-level loader orchestration into a host-owned module before enforcing the loader lifecycle state machine +- by moving record-state transitions first into a compatibility layer and then into an enforced loader lifecycle state machine - by moving cache writes, provenance warnings, final memory-slot warnings, and activation into a host-owned loader finalizer before introducing an explicit lifecycle state machine -- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before introducing the full lifecycle state machine +- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before enforcing the loader lifecycle state machine +- by promoting successfully registered plugins to `ready` during host-owned finalization while leaving broader activation-state semantics for later phases What is still pending from this spec: -- the full lifecycle state machine +- broader extension-host lifecycle ownership beyond the loader state machine - activation pipeline ownership - host-owned registries for setup, CLI, routes, services, slots, and backends - permission-mode enforcement diff --git a/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md b/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md index 14e61fc43da..16184f94630 100644 --- a/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md +++ b/docs/.internal/extension-host-migration/openclaw-kernel-event-pipeline-spec.md @@ -44,7 +44,7 @@ Relevant prerequisite work that has landed: - loader post-import planning and `register(...)` execution now have a host-owned helper boundary - loader per-candidate orchestration now has a host-owned helper boundary - loader top-level load orchestration now has a host-owned helper boundary -- loader record-state transitions now have a host-owned helper boundary, including explicit compatibility `lifecycleState` mapping +- loader record-state transitions now have a host-owned helper boundary and enforced loader lifecycle state machine, while still preserving compatibility `PluginRecord.status` values - loader final cache, warning, and activation finalization now has a host-owned helper boundary Why this matters for this spec: diff --git a/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md b/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md index c212ae42bfa..bd77cd2ed39 100644 --- a/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md +++ b/docs/.internal/extension-host-migration/openclaw-kernel-extension-host-transition-plan.md @@ -54,7 +54,7 @@ What has landed: - loader post-import planning and `register(...)` execution now route through `src/extension-host/loader-register.ts` - loader per-candidate orchestration now routes through `src/extension-host/loader-flow.ts` - loader top-level load orchestration now routes through `src/extension-host/loader-orchestrator.ts` -- loader record-state transitions now route through `src/extension-host/loader-state.ts`, including explicit compatibility `lifecycleState` mapping +- loader record-state transitions now route through `src/extension-host/loader-state.ts`, which now enforces an explicit loader lifecycle state machine while preserving compatibility `PluginRecord.status` values - loader final cache, warning, and activation finalization now routes through `src/extension-host/loader-finalize.ts` - runtime registration normalization has started in `src/extension-host/runtime-registrations.ts` for channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook registrations - several existing consumers now read host-owned normalized data instead of plugin-era manifest or runtime state directly: @@ -85,9 +85,10 @@ How it was done: - by moving loader runtime decisions next, while preserving lazy loading, config validation behavior, and memory-slot policy behavior - by moving post-import planning and `register(...)` execution behind host-owned helpers before changing entry-path and import flow - by composing those seams into one host-owned per-candidate orchestrator before changing cache and lifecycle finalization behavior -- by moving loader record-state transitions into host-owned helpers before introducing a full lifecycle state machine +- by moving loader record-state transitions into host-owned helpers before enforcing them as a loader lifecycle state machine - by moving cache writes, provenance warnings, final memory-slot warnings, and activation into a host-owned loader finalizer before introducing an explicit lifecycle state machine -- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before introducing a full lifecycle state machine +- by adding explicit compatibility `lifecycleState` mapping on loader-owned plugin records before enforcing the loader lifecycle state machine +- by turning that compatibility `lifecycleState` field into an enforced loader lifecycle state machine with readiness promotion during finalization - by moving the remaining top-level loader orchestration into a host-owned module so `src/plugins/loader.ts` becomes a compatibility facade instead of the real owner - by moving static and lookup-heavy consumers first, where the ownership boundary matters but runtime risk is lower @@ -103,13 +104,14 @@ Committed implementation slices so far: - `33ef55a9ee` `Plugins: add loader lifecycle state mapping` - `6590e19095` `Plugins: extract loader cache control` - `c8d82a8f19` `Plugins: extract loader orchestration` +- `d32f65eb5e` `Plugins: add loader lifecycle state machine` - `89414ed857` `Docs: track extension host migration internally` - `d8af1eceaf` `Docs: refresh extension host migration status` What has not landed: - keeping the cutover inventory current as more surfaces move -- the full lifecycle state machine and remaining explicit activation-state and policy semantics +- broader lifecycle ownership beyond the loader state machine, plus remaining explicit activation-state and policy semantics - host-owned registration surfaces beyond the first channel, provider, HTTP-route, gateway-method, tool, CLI, service, command, context-engine, and hook helper slices - SDK compatibility translation work - canonical event stages @@ -1326,7 +1328,7 @@ Current implementation status: - the host now owns active registry state - the host now exposes resolved static registries for static consumers - activation, loader cache control, loader policy, loader runtime decisions, loader top-level load orchestration, loader record-state helpers, and loader finalization now route through `src/extension-host/*` -- broader lifecycle ownership, registration surfaces, policy gates, and activation-state management are still pending +- broader lifecycle ownership beyond the loader state machine, registration surfaces, policy gates, and activation-state management are still pending ## Phase 3: Broader Legacy Compatibility Bridges