Add overlay plugin lifecycle.

PR Details:
- Standardizes plugin lifecycle behavior

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,8 +2,8 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement overlay plugin registry:
-- Add registration system
-- Validate with one plugin
+Implement plugin lifecycle:
+- Add init/activate/deactivate/destroy phases
+- Ensure safe transitions
+- Validate with test plugin
 - Update roadmap status only
-- Package ZIP

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Add overlay plugin registry.
+Add overlay plugin lifecycle.
 
 PR Details:
-- Enables structured overlay registration
+- Standardizes plugin lifecycle behavior

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Plugin registers
-[ ] Plugin activates
-[ ] Plugin removes cleanly
+[ ] Init works
+[ ] Activate/deactivate stable
+[ ] Destroy cleans up
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -819,7 +819,7 @@
 
 ### Track G — Extensibility Readiness
 - [x] validate plugin/extension patterns
-- [ ] validate adding new systems is clean
+- [.] validate adding new systems is clean
 - [ ] validate external integration points
 - [ ] ensure future phases can build cleanly
 

docs/pr/BUILD_PR.md

@@ -1,20 +1,21 @@
-# BUILD_PR_LEVEL_20_2_OVERLAY_PLUGIN_REGISTRY
+# BUILD_PR_LEVEL_20_3_OVERLAY_PLUGIN_LIFECYCLE
 
 ## Purpose
-Introduce a registry for managing overlay plugins.
+Define lifecycle for overlay plugins from init to teardown.
 
 ## Roadmap Improvement
-Enables structured registration and discovery of overlays.
+Completes plugin system foundation by standardizing lifecycle behavior.
 
 ## Scope
-- Define plugin registry
-- Allow registration/unregistration
-- Validate with one plugin
+- Define init, activate, deactivate, destroy phases
+- Ensure safe transitions between states
+- Validate lifecycle with one plugin
 
 ## Test Steps
 1. Register plugin
-2. Activate overlay
-3. Remove plugin
+2. Activate/deactivate multiple times
+3. Destroy plugin
 
 ## Expected
-- Plugins managed cleanly
+- Clean lifecycle transitions
+- No memory or state leaks

samples/phase-19/shared/overlay/createPhase19OverlayPluginRegistry.js

@@ -6,6 +6,13 @@ createPhase19OverlayPluginRegistry.js
 */
 import createPhase19OverlayExpansionFramework from '/samples/phase-19/shared/overlay/createPhase19OverlayExpansionFramework.js';
 
+const PLUGIN_STATES = Object.freeze({
+  REGISTERED: 'registered',
+  INITIALIZED: 'initialized',
+  ACTIVE: 'active',
+  INACTIVE: 'inactive',
+});
+
 function normalizePluginId(pluginId) {
   return String(pluginId || '').trim();
 }
@@ -35,6 +42,16 @@ function normalizePluginDefinition(plugin) {
     id,
     version: String(plugin.version || '').trim(),
     metadata: Object.freeze({ ...(plugin.metadata || {}) }),
+    init: typeof plugin.init === 'function' ? plugin.init : (typeof plugin.onInit === 'function' ? plugin.onInit : null),
+    activate: typeof plugin.activate === 'function'
+      ? plugin.activate
+      : (typeof plugin.onActivate === 'function' ? plugin.onActivate : null),
+    deactivate: typeof plugin.deactivate === 'function'
+      ? plugin.deactivate
+      : (typeof plugin.onDeactivate === 'function' ? plugin.onDeactivate : null),
+    destroy: typeof plugin.destroy === 'function'
+      ? plugin.destroy
+      : (typeof plugin.onDestroy === 'function' ? plugin.onDestroy : null),
     createOverlayExtension,
     extension,
   });
@@ -58,14 +75,133 @@ export default function createPhase19OverlayPluginRegistry({
   expansionFramework = createPhase19OverlayExpansionFramework(),
   plugins = [],
 } = {}) {
-  const pluginMap = new Map();
-  const pluginExtensionMap = new Map();
+  const pluginRecordMap = new Map();
   let api = null;
 
-  function registerPlugin(plugin, context = {}) {
+  function getPluginRecord(pluginId) {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    if (!normalizedPluginId) {
+      return null;
+    }
+    return pluginRecordMap.get(normalizedPluginId) ?? null;
+  }
+
+  function runLifecycleHook(record, phase, context = {}) {
+    const hook = record?.plugin?.[phase];
+    if (typeof hook !== 'function') {
+      return true;
+    }
+    try {
+      hook({
+        ...context,
+        phase,
+        pluginId: record.plugin.id,
+        extensionId: record.extension.id,
+        registry: api,
+        expansionFramework,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function initPlugin(pluginId, context = {}) {
+    const record = getPluginRecord(pluginId);
+    if (!record) {
+      return false;
+    }
+    if (record.state === PLUGIN_STATES.INITIALIZED || record.state === PLUGIN_STATES.ACTIVE || record.state === PLUGIN_STATES.INACTIVE) {
+      return false;
+    }
+    if (record.state !== PLUGIN_STATES.REGISTERED) {
+      return false;
+    }
+    if (!runLifecycleHook(record, 'init', context)) {
+      return false;
+    }
+    record.state = PLUGIN_STATES.INITIALIZED;
+    return true;
+  }
+
+  function activatePlugin(pluginId, context = {}) {
+    const record = getPluginRecord(pluginId);
+    if (!record) {
+      return false;
+    }
+    if (record.state === PLUGIN_STATES.ACTIVE) {
+      return false;
+    }
+    if (record.state === PLUGIN_STATES.REGISTERED) {
+      if (!initPlugin(pluginId, context)) {
+        return false;
+      }
+    }
+    if (record.state !== PLUGIN_STATES.INITIALIZED && record.state !== PLUGIN_STATES.INACTIVE) {
+      return false;
+    }
+
+    const registered = expansionFramework.registerExtension(record.extension);
+    if (!registered || !registered.id) {
+      return false;
+    }
+
+    if (!runLifecycleHook(record, 'activate', context)) {
+      expansionFramework.unregisterExtension(record.extension.id);
+      return false;
+    }
+
+    record.state = PLUGIN_STATES.ACTIVE;
+    return true;
+  }
+
+  function deactivatePlugin(pluginId, context = {}) {
+    const record = getPluginRecord(pluginId);
+    if (!record) {
+      return false;
+    }
+    if (record.state !== PLUGIN_STATES.ACTIVE) {
+      return false;
+    }
+    if (!runLifecycleHook(record, 'deactivate', context)) {
+      return false;
+    }
+
+    expansionFramework.unregisterExtension(record.extension.id);
+    record.state = PLUGIN_STATES.INACTIVE;
+    return true;
+  }
+
+  function destroyPlugin(pluginId, context = {}) {
+    const normalizedPluginId = normalizePluginId(pluginId);
+    const record = getPluginRecord(normalizedPluginId);
+    if (!record) {
+      return false;
+    }
+    if (record.state === PLUGIN_STATES.ACTIVE) {
+      if (!deactivatePlugin(normalizedPluginId, context)) {
+        return false;
+      }
+    }
+    if (!runLifecycleHook(record, 'destroy', context)) {
+      return false;
+    }
+
+    expansionFramework.unregisterExtension(record.extension.id);
+    pluginRecordMap.delete(normalizedPluginId);
+    return true;
+  }
+
+  function registerPlugin(plugin, options = {}) {
+    const context = options?.context || {};
+    const autoActivate = options?.autoActivate !== false;
     const normalizedPlugin = normalizePluginDefinition(plugin);
     const pluginId = normalizedPlugin.id;
 
+    if (pluginRecordMap.has(pluginId)) {
+      destroyPlugin(pluginId, { ...context, reason: 're-register' });
+    }
+
     const resolvedExtension = normalizePluginExtension(
       normalizedPlugin,
       normalizedPlugin.createOverlayExtension
@@ -78,70 +214,70 @@ export default function createPhase19OverlayPluginRegistry({
         : normalizedPlugin.extension
     );
 
-    const existingExtensionId = pluginExtensionMap.get(pluginId);
-    if (existingExtensionId) {
-      expansionFramework.unregisterExtension(existingExtensionId);
-    }
+    const record = {
+      plugin: normalizedPlugin,
+      extension: resolvedExtension,
+      state: PLUGIN_STATES.REGISTERED,
+    };
+    pluginRecordMap.set(pluginId, record);
 
-    const registeredExtension = expansionFramework.registerExtension(resolvedExtension);
-    pluginMap.set(pluginId, normalizedPlugin);
-    pluginExtensionMap.set(pluginId, registeredExtension.id);
+    if (autoActivate) {
+      if (!activatePlugin(pluginId, context)) {
+        pluginRecordMap.delete(pluginId);
+        throw new Error(`Overlay plugin "${pluginId}" failed lifecycle activation.`);
+      }
+    }
 
     return Object.freeze({
       pluginId,
-      extensionId: registeredExtension.id,
+      extensionId: resolvedExtension.id,
     });
   }
 
-  function unregisterPlugin(pluginId) {
-    const normalizedPluginId = normalizePluginId(pluginId);
-    if (!normalizedPluginId || !pluginMap.has(normalizedPluginId)) {
-      return false;
-    }
-
-    const extensionId = pluginExtensionMap.get(normalizedPluginId);
-    if (extensionId) {
-      expansionFramework.unregisterExtension(extensionId);
-    }
-    pluginExtensionMap.delete(normalizedPluginId);
-    pluginMap.delete(normalizedPluginId);
-    return true;
+  function unregisterPlugin(pluginId, context = {}) {
+    return destroyPlugin(pluginId, context);
   }
 
   function getPlugin(pluginId) {
-    const normalizedPluginId = normalizePluginId(pluginId);
-    if (!normalizedPluginId) {
-      return null;
-    }
-    return pluginMap.get(normalizedPluginId) ?? null;
+    const record = getPluginRecord(pluginId);
+    return record ? record.plugin : null;
+  }
+
+  function getPluginState(pluginId) {
+    const record = getPluginRecord(pluginId);
+    return record?.state || '';
   }
 
   function getPluginExtensionId(pluginId) {
-    const normalizedPluginId = normalizePluginId(pluginId);
-    if (!normalizedPluginId) {
-      return '';
-    }
-    return pluginExtensionMap.get(normalizedPluginId) || '';
+    const record = getPluginRecord(pluginId);
+    return record?.extension?.id || '';
   }
 
   function listPlugins() {
     const entries = [];
-    for (const [pluginId, plugin] of pluginMap.entries()) {
+    for (const [pluginId, record] of pluginRecordMap.entries()) {
       entries.push({
         id: pluginId,
-        version: plugin.version,
-        extensionId: pluginExtensionMap.get(pluginId) || '',
+        version: record.plugin.version,
+        extensionId: record.extension.id,
+        state: record.state,
       });
     }
     return Object.freeze(entries);
   }
 
   api = {
     registerPlugin,
+    initPlugin,
+    activatePlugin,
+    deactivatePlugin,
+    destroyPlugin,
     unregisterPlugin,
     getPlugin,
+    getPluginState,
     getPluginExtensionId,
     listPlugins,
+    states: PLUGIN_STATES,
     getFramework() {
       return expansionFramework;
     },