@pellux/goodvibes-sdk 0.18.13 → 0.18.15

package/dist/_internal/platform/runtime/plugins/lifecycle.js

@@ -0,0 +1,78 @@
+/**
+ * Plugin lifecycle state machine.
+ *
+ * Defines the valid state transitions for the 8-state plugin lifecycle
+ * and provides pure guard/transition functions with no side effects.
+ *
+ * States:
+ *   discovered → loading → loaded → active ↔ degraded
+ *                                          ↓
+ *                                        error → (unloading | disabled)
+ *                    active/loaded/degraded/error → unloading → disabled
+ *                    any → error (non-fatal)
+ *                    disabled → loading (re-enable)
+ */
+/**
+ * Adjacency map: from state → set of valid target states.
+ *
+ * Encoded as a plain Record so it is safe to evaluate at module load time
+ * with no external dependencies.
+ */
+export const VALID_TRANSITIONS = {
+    discovered: ['loading'],
+    loading: ['loaded', 'error'],
+    loaded: ['active', 'error', 'unloading'],
+    active: ['degraded', 'error', 'unloading'],
+    degraded: ['active', 'error', 'unloading'],
+    error: ['unloading', 'disabled', 'loading'],
+    unloading: ['disabled'],
+    disabled: ['loading'],
+};
+/**
+ * Returns whether a transition from `from` → `to` is permitted by the
+ * state machine.
+ */
+export function canTransition(from, to) {
+    return VALID_TRANSITIONS[from].includes(to);
+}
+/**
+ * Attempts a state transition and returns a typed result.
+ *
+ * This is a pure function — it has no side effects. The caller is responsible
+ * for updating the plugin record and emitting events.
+ *
+ * @param from - Current state.
+ * @param to   - Desired target state.
+ * @returns `{ ok: true, from, to }` on success or `{ ok: false, reason }` on
+ *          invalid transition.
+ */
+export function applyTransition(from, to) {
+    if (canTransition(from, to)) {
+        return { ok: true, from, to };
+    }
+    return {
+        ok: false,
+        reason: `Invalid transition: ${from} → ${to} (allowed from ${from}: [${VALID_TRANSITIONS[from].join(', ')}])`,
+    };
+}
+/**
+ * Returns whether a plugin in the given state is considered "operational"
+ * (i.e. actively servicing requests, possibly in a degraded capacity).
+ */
+export function isOperational(state) {
+    return state === 'active' || state === 'degraded';
+}
+/**
+ * Returns whether a plugin in the given state can be safely hot-reloaded.
+ * A hot reload requires the plugin to be quiesceable.
+ */
+export function isReloadable(state) {
+    return state === 'active' || state === 'loaded' || state === 'degraded' || state === 'error';
+}
+/**
+ * Returns whether the plugin's current state represents a terminal failure
+ * that requires operator intervention (disabled or persistent error).
+ */
+export function isTerminal(state) {
+    return state === 'disabled';
+}

package/dist/_internal/platform/runtime/plugins/manager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * PluginLifecycleManager — plugin lifecycle and capability enforcement.
+ *
+ * Tracks all plugins through the 8-state lifecycle machine, resolves capability
+ * manifests on load, and emits PluginEvents at every state transition.
+ *
+ * Gated by the `plugin-lifecycle` feature flag.
+ */
+import type { PluginLoaderDeps, LoadedPlugin } from '../../plugins/loader.js';
+import { type PluginPathOptions } from '../../plugins/loader.js';
+import type { PluginLifecycleState } from '@pellux/goodvibes-sdk/platform/runtime/store/domains/plugins';
+import { type PluginLifecycleManagerOptions, type PluginLifecycleRecord, type PluginManifestV2 } from './types.js';
+import { PluginTrustStore, type PluginTrustTier } from './trust.js';
+import { PluginQuarantineEngine } from './quarantine.js';
+/**
+ * PluginLifecycleManager tracks all plugins through structured lifecycle
+ * transitions and emits typed PluginEvents at each state change.
+ */
+export declare class PluginLifecycleManager {
+    private readonly records;
+    private readonly sessionId;
+    private readonly capabilityPolicy;
+    private readonly trustTierResolver;
+    private readonly runtimeBus;
+    /** Trust store — manages tier records for all plugins. */
+    readonly trustStore: PluginTrustStore;
+    /** Quarantine engine — tracks and applies quarantine constraints. */
+    readonly quarantine: PluginQuarantineEngine;
+    constructor(options?: PluginLifecycleManagerOptions);
+    /** Returns the lifecycle record for a plugin, or undefined if unknown. */
+    getRecord(name: string): Readonly<PluginLifecycleRecord> | undefined;
+    /** Returns all plugin lifecycle records as an array. */
+    getAllRecords(): ReadonlyArray<Readonly<PluginLifecycleRecord>>;
+    /** Returns names of all plugins in a given state. */
+    getPluginsInState(state: PluginLifecycleState): string[];
+    /** Returns names of all currently operational plugins (active or degraded). */
+    getOperationalPlugins(): string[];
+    /**
+     * Register a discovered plugin. Creates its lifecycle record in the
+     * `discovered` state and emits PLUGIN_DISCOVERED.
+     */
+    registerDiscovered(manifest: PluginManifestV2, pluginDir: string): void;
+    /**
+     * Load a plugin using the existing loader infrastructure.
+     *
+     * Transitions: discovered/disabled → loading → loaded → active
+     * On failure:  loading → error
+     */
+    loadPlugin(manifest: PluginManifestV2, pluginDir: string, deps: PluginLoaderDeps, cacheBust?: number): Promise<boolean>;
+    /**
+     * Unload a plugin. Transitions active/loaded/degraded → unloading → disabled.
+     */
+    unloadPlugin(name: string, reason?: string, loaderDeps?: {
+        getLoadedPlugin?: (name: string) => LoadedPlugin | undefined;
+    }): Promise<void>;
+    /**
+     * setTrustTier — Assign a trust tier to a plugin and re-sync the record.
+     *
+     * If the plugin has an active lifecycle record, the trust tier in the record
+     * is updated immediately. Capability re-resolution requires a reload.
+     */
+    setTrustTier(name: string, tier: PluginTrustTier, note?: string): void;
+    /**
+     * quarantinePlugin — Apply quarantine to a named plugin.
+     *
+     * Revokes high-risk capabilities from the live manifest and marks the record
+     * as quarantined. Emits PLUGIN_DEGRADED to signal partial functionality.
+     *
+     * @returns true if quarantine was applied; false if not tracked or already quarantined.
+     */
+    quarantinePlugin(name: string, reason: string): boolean;
+    /**
+     * liftQuarantine — Remove quarantine from a plugin.
+     *
+     * Capabilities are NOT restored here; the operator should reload the plugin
+     * after lifting so that trust-aware re-resolution can grant capabilities
+     * appropriate for the updated tier.
+     *
+     * @returns true if quarantine was lifted; false if no active quarantine.
+     */
+    liftQuarantine(name: string): boolean;
+    /**
+     * Mark a plugin as degraded (partial functionality). Only valid from active.
+     */
+    degradePlugin(name: string, reason: string, affectedCapabilities?: string[]): void;
+    /**
+     * Record a non-fatal error without transitioning state.
+     * If the plugin is active, it may optionally be moved to degraded.
+     */
+    recordError(name: string, error: string, fatal: boolean): void;
+    /**
+     * Scan for plugins and register newly discovered ones.
+     * Existing records are not modified.
+     */
+    scanAndRegister(pathOptions: PluginPathOptions): void;
+    /**
+     * Apply a state machine transition for a named plugin.
+     * Records the transition in the plugin's history.
+     * Returns the TransitionResult from the state machine.
+     */
+    private transition;
+    /**
+     * Partially update a plugin record's mutable fields.
+     */
+    private updateRecord;
+    private emit;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/_internal/platform/runtime/plugins/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/plugins/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACzG,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EAGtB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAgBzD;;;GAGG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmD;IACpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0C;IAC5E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IAErD,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAA0B;IAC/D,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAgC;gBAE/D,OAAO,GAAE,6BAAkC;IASvD,0EAA0E;IAC1E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,qBAAqB,CAAC,GAAG,SAAS;IAIpE,wDAAwD;IACxD,aAAa,IAAI,aAAa,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAI/D,qDAAqD;IACrD,iBAAiB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,EAAE;IAQxD,+EAA+E;IAC/E,qBAAqB,IAAI,MAAM,EAAE;IAUjC;;;OAGG;IACH,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAiCvE;;;;;OAKG;IACG,UAAU,CACd,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,gBAAgB,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IAsEnB;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,GAAG,SAAS,CAAA;KAAE,GAC5E,OAAO,CAAC,IAAI,CAAC;IAiChB;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAStE;;;;;;;OAOG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAsBvD;;;;;;;;OAQG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAYrC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAE,MAAM,EAAO,GAAG,IAAI;IAoBtF;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAgB9D;;;OAGG;IACH,eAAe,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAYrD;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA8BlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,IAAI;CAqCb"}

package/dist/_internal/platform/runtime/plugins/manager.js

@@ -0,0 +1,387 @@
+/**
+ * PluginLifecycleManager — plugin lifecycle and capability enforcement.
+ *
+ * Tracks all plugins through the 8-state lifecycle machine, resolves capability
+ * manifests on load, and emits PluginEvents at every state transition.
+ *
+ * Gated by the `plugin-lifecycle` feature flag.
+ */
+import { logger } from '@pellux/goodvibes-sdk/platform/utils/logger';
+import { RuntimeEventBus } from '../events/index.js';
+import { discoverPlugins, loadPlugin, unloadPlugin, } from '../../plugins/loader.js';
+import { MAX_TRANSITION_HISTORY, } from './types.js';
+import { applyTransition, isOperational } from './lifecycle.js';
+import { resolveCapabilityManifest } from './manifest.js';
+import { PluginTrustStore } from './trust.js';
+import { PluginQuarantineEngine } from './quarantine.js';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils/error-display';
+import { emitPluginActive, emitPluginDegraded, emitPluginDisabled, emitPluginDiscovered, emitPluginError, emitPluginLoaded, emitPluginLoading, emitPluginUnloading, } from '../emitters/plugins.js';
+/** Source label for emitted events. */
+const EVENT_SOURCE = 'plugin-lifecycle-manager';
+/**
+ * PluginLifecycleManager tracks all plugins through structured lifecycle
+ * transitions and emits typed PluginEvents at each state change.
+ */
+export class PluginLifecycleManager {
+    records = new Map();
+    sessionId;
+    capabilityPolicy;
+    trustTierResolver;
+    runtimeBus;
+    /** Trust store — manages tier records for all plugins. */
+    trustStore = new PluginTrustStore();
+    /** Quarantine engine — tracks and applies quarantine constraints. */
+    quarantine = new PluginQuarantineEngine();
+    constructor(options = {}) {
+        this.sessionId = options.sessionId ?? '';
+        this.capabilityPolicy = options.capabilityPolicy ?? (() => true);
+        this.trustTierResolver = options.trustTierResolver ?? ((name) => this.trustStore.getTier(name));
+        this.runtimeBus = options.runtimeBus ?? new RuntimeEventBus();
+    }
+    // ── Plugin record accessors ────────────────────────────────────────────────
+    /** Returns the lifecycle record for a plugin, or undefined if unknown. */
+    getRecord(name) {
+        return this.records.get(name);
+    }
+    /** Returns all plugin lifecycle records as an array. */
+    getAllRecords() {
+        return Array.from(this.records.values());
+    }
+    /** Returns names of all plugins in a given state. */
+    getPluginsInState(state) {
+        const result = [];
+        for (const [name, record] of this.records) {
+            if (record.state === state)
+                result.push(name);
+        }
+        return result;
+    }
+    /** Returns names of all currently operational plugins (active or degraded). */
+    getOperationalPlugins() {
+        const result = [];
+        for (const [name, record] of this.records) {
+            if (isOperational(record.state))
+                result.push(name);
+        }
+        return result;
+    }
+    // ── Lifecycle operations ──────────────────────────────────────────────────
+    /**
+     * Register a discovered plugin. Creates its lifecycle record in the
+     * `discovered` state and emits PLUGIN_DISCOVERED.
+     */
+    registerDiscovered(manifest, pluginDir) {
+        const name = manifest.name;
+        if (this.records.has(name)) {
+            logger.debug(`[plugin-lifecycle] ${name}: already registered, skipping re-registration`);
+            return;
+        }
+        const tier = this.trustTierResolver(name);
+        const capabilities = resolveCapabilityManifest(name, manifest, this.capabilityPolicy, tier);
+        const record = {
+            name,
+            version: manifest.version,
+            state: 'discovered',
+            capabilities,
+            transitions: [],
+            reloading: false,
+            trustTier: tier,
+            quarantined: this.quarantine.isQuarantined(name),
+        };
+        this.records.set(name, record);
+        this.emit({
+            type: 'PLUGIN_DISCOVERED',
+            pluginId: name,
+            path: pluginDir,
+            version: manifest.version,
+        });
+        logger.debug(`[plugin-lifecycle] ${name}@${manifest.version}: registered (discovered)`);
+    }
+    /**
+     * Load a plugin using the existing loader infrastructure.
+     *
+     * Transitions: discovered/disabled → loading → loaded → active
+     * On failure:  loading → error
+     */
+    async loadPlugin(manifest, pluginDir, deps, cacheBust) {
+        const name = manifest.name;
+        let record = this.records.get(name);
+        if (!record) {
+            this.registerDiscovered(manifest, pluginDir);
+            record = this.records.get(name);
+        }
+        // discovered → loading (or disabled → loading for re-enable)
+        const toLoadingResult = this.transition(name, 'loading');
+        if (!toLoadingResult.ok) {
+            logger.warn(`[plugin-lifecycle] ${name}: cannot start load — ${toLoadingResult.reason}`);
+            return false;
+        }
+        this.emit({ type: 'PLUGIN_LOADING', pluginId: name, path: pluginDir });
+        try {
+            const loaded = await loadPlugin({ manifest, pluginDir }, deps, cacheBust);
+            if (!loaded) {
+                this.transition(name, 'error', 'loadPlugin returned null');
+                this.updateRecord(name, { lastError: 'loadPlugin returned null', errorAt: Date.now() });
+                this.emit({
+                    type: 'PLUGIN_ERROR',
+                    pluginId: name,
+                    error: 'loadPlugin returned null',
+                    fatal: false,
+                });
+                return false;
+            }
+            // loading → loaded
+            this.transition(name, 'loaded');
+            // loaded → active
+            const toActiveResult = this.transition(name, 'active');
+            if (!toActiveResult.ok) {
+                logger.warn(`[plugin-lifecycle] ${name}: cannot transition to active — ${toActiveResult.reason}`);
+                return false;
+            }
+            this.updateRecord(name, { activatedAt: Date.now() });
+            this.emit({
+                type: 'PLUGIN_LOADED',
+                pluginId: name,
+                version: manifest.version,
+                capabilities: record.capabilities.granted,
+            });
+            this.emit({ type: 'PLUGIN_ACTIVE', pluginId: name });
+            logger.info(`[plugin-lifecycle] ${name}@${manifest.version}: active`);
+            return true;
+        }
+        catch (err) {
+            const errorMsg = summarizeError(err);
+            this.transition(name, 'error', errorMsg);
+            this.updateRecord(name, { lastError: errorMsg, errorAt: Date.now() });
+            this.emit({
+                type: 'PLUGIN_ERROR',
+                pluginId: name,
+                error: errorMsg,
+                fatal: false,
+            });
+            logger.error(`[plugin-lifecycle] ${name}: load threw — ${errorMsg}`);
+            return false;
+        }
+    }
+    /**
+     * Unload a plugin. Transitions active/loaded/degraded → unloading → disabled.
+     */
+    async unloadPlugin(name, reason, loaderDeps) {
+        const record = this.records.get(name);
+        if (!record) {
+            logger.debug(`[plugin-lifecycle] ${name}: unload requested but not tracked`);
+            return;
+        }
+        const toUnloadingResult = this.transition(name, 'unloading', reason);
+        if (!toUnloadingResult.ok) {
+            logger.warn(`[plugin-lifecycle] ${name}: cannot unload — ${toUnloadingResult.reason}`);
+            return;
+        }
+        this.emit({ type: 'PLUGIN_UNLOADING', pluginId: name, reason });
+        // Delegate to the existing unloadPlugin function if a loaded instance is available.
+        const loadedPlugin = loaderDeps?.getLoadedPlugin?.(name);
+        if (loadedPlugin) {
+            await unloadPlugin(loadedPlugin);
+        }
+        this.transition(name, 'disabled', reason);
+        this.emit({
+            type: 'PLUGIN_DISABLED',
+            pluginId: name,
+            reason: reason ?? 'unloaded',
+        });
+        logger.info(`[plugin-lifecycle] ${name}: disabled${reason ? ` (${reason})` : ''}`);
+    }
+    // ── Trust & Quarantine operations ────────────────────────────────────────
+    /**
+     * setTrustTier — Assign a trust tier to a plugin and re-sync the record.
+     *
+     * If the plugin has an active lifecycle record, the trust tier in the record
+     * is updated immediately. Capability re-resolution requires a reload.
+     */
+    setTrustTier(name, tier, note) {
+        this.trustStore.setTier(name, tier, { note });
+        const record = this.records.get(name);
+        if (record) {
+            record.trustTier = tier;
+        }
+        logger.info(`[plugin-lifecycle] ${name}: trust tier set to '${tier}'${note ? ` — ${note}` : ''}`);
+    }
+    /**
+     * quarantinePlugin — Apply quarantine to a named plugin.
+     *
+     * Revokes high-risk capabilities from the live manifest and marks the record
+     * as quarantined. Emits PLUGIN_DEGRADED to signal partial functionality.
+     *
+     * @returns true if quarantine was applied; false if not tracked or already quarantined.
+     */
+    quarantinePlugin(name, reason) {
+        const record = this.records.get(name);
+        if (!record) {
+            logger.warn(`[plugin-lifecycle] ${name}: quarantine requested but plugin not tracked`);
+            return false;
+        }
+        const qRecord = this.quarantine.quarantine(name, record.capabilities, reason);
+        if (!qRecord)
+            return false;
+        record.quarantined = true;
+        this.emit({
+            type: 'PLUGIN_DEGRADED',
+            pluginId: name,
+            reason: `quarantined: ${reason}`,
+            affectedCapabilities: qRecord.revokedCapabilities,
+        });
+        return true;
+    }
+    /**
+     * liftQuarantine — Remove quarantine from a plugin.
+     *
+     * Capabilities are NOT restored here; the operator should reload the plugin
+     * after lifting so that trust-aware re-resolution can grant capabilities
+     * appropriate for the updated tier.
+     *
+     * @returns true if quarantine was lifted; false if no active quarantine.
+     */
+    liftQuarantine(name) {
+        const lifted = this.quarantine.lift(name);
+        const record = this.records.get(name);
+        if (record) {
+            record.quarantined = false;
+        }
+        if (lifted) {
+            logger.info(`[plugin-lifecycle] ${name}: quarantine lifted — reload to restore capabilities`);
+        }
+        return lifted;
+    }
+    /**
+     * Mark a plugin as degraded (partial functionality). Only valid from active.
+     */
+    degradePlugin(name, reason, affectedCapabilities = []) {
+        const record = this.records.get(name);
+        if (!record)
+            return;
+        const result = this.transition(name, 'degraded', reason);
+        if (!result.ok) {
+            logger.warn(`[plugin-lifecycle] ${name}: cannot degrade — ${result.reason}`);
+            return;
+        }
+        this.emit({
+            type: 'PLUGIN_DEGRADED',
+            pluginId: name,
+            reason,
+            affectedCapabilities,
+        });
+        logger.warn(`[plugin-lifecycle] ${name}: degraded — ${reason}`);
+    }
+    /**
+     * Record a non-fatal error without transitioning state.
+     * If the plugin is active, it may optionally be moved to degraded.
+     */
+    recordError(name, error, fatal) {
+        const record = this.records.get(name);
+        if (!record)
+            return;
+        this.updateRecord(name, { lastError: error, errorAt: Date.now() });
+        this.emit({ type: 'PLUGIN_ERROR', pluginId: name, error, fatal });
+        if (fatal && (record.state === 'active' || record.state === 'loaded' || record.state === 'degraded')) {
+            this.transition(name, 'error', error);
+        }
+        logger.error(`[plugin-lifecycle] ${name}: error (fatal=${String(fatal)}) — ${error}`);
+    }
+    // ── Bulk operations ───────────────────────────────────────────────────────
+    /**
+     * Scan for plugins and register newly discovered ones.
+     * Existing records are not modified.
+     */
+    scanAndRegister(pathOptions) {
+        const discovered = discoverPlugins(pathOptions);
+        for (const { manifest, pluginDir } of discovered) {
+            if (!this.records.has(manifest.name)) {
+                this.registerDiscovered(manifest, pluginDir);
+            }
+        }
+        logger.debug(`[plugin-lifecycle] Scan complete: ${discovered.length} plugin(s) found`);
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────
+    /**
+     * Apply a state machine transition for a named plugin.
+     * Records the transition in the plugin's history.
+     * Returns the TransitionResult from the state machine.
+     */
+    transition(name, to, reason) {
+        const record = this.records.get(name);
+        if (!record)
+            return { ok: false, reason: `Plugin '${name}' not tracked` };
+        const result = applyTransition(record.state, to);
+        if (!result.ok)
+            return result;
+        const entry = {
+            pluginName: name,
+            from: result.from,
+            to: result.to,
+            ts: Date.now(),
+            reason,
+        };
+        // Mutate the record in place — the record lives inside the Map.
+        record.transitions.push(entry);
+        if (record.transitions.length > MAX_TRANSITION_HISTORY) {
+            record.transitions.shift();
+        }
+        record.state = to;
+        logger.debug(`[plugin-lifecycle] ${name}: ${result.from} → ${to}${reason ? ` (${reason})` : ''}`);
+        return { ok: true };
+    }
+    /**
+     * Partially update a plugin record's mutable fields.
+     */
+    updateRecord(name, patch) {
+        const record = this.records.get(name);
+        if (!record)
+            return;
+        if (patch.lastError !== undefined)
+            record.lastError = patch.lastError;
+        if (patch.errorAt !== undefined)
+            record.errorAt = patch.errorAt;
+        if (patch.activatedAt !== undefined)
+            record.activatedAt = patch.activatedAt;
+        if (patch.reloading !== undefined)
+            record.reloading = patch.reloading;
+    }
+    emit(event) {
+        const ctx = {
+            sessionId: this.sessionId,
+            traceId: `plugin-lifecycle:${event.pluginId}`,
+            source: EVENT_SOURCE,
+        };
+        try {
+            switch (event.type) {
+                case 'PLUGIN_DISCOVERED':
+                    emitPluginDiscovered(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_LOADING':
+                    emitPluginLoading(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_LOADED':
+                    emitPluginLoaded(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_ACTIVE':
+                    emitPluginActive(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_DEGRADED':
+                    emitPluginDegraded(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_ERROR':
+                    emitPluginError(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_UNLOADING':
+                    emitPluginUnloading(this.runtimeBus, ctx, event);
+                    break;
+                case 'PLUGIN_DISABLED':
+                    emitPluginDisabled(this.runtimeBus, ctx, event);
+                    break;
+            }
+        }
+        catch (err) {
+            logger.debug(`[plugin-lifecycle] runtime emit failed: ${summarizeError(err)}`);
+        }
+    }
+}

package/dist/_internal/platform/runtime/plugins/manifest.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Plugin capability manifest validation and resolution.
+ *
+ * Implements deny-by-default capability enforcement:
+ * 1. Parse raw manifest capabilities (unknown → typed)
+ * 2. Validate that each requested capability is a known capability
+ * 3. Run the runtime's capability policy to grant or deny each capability
+ * 4. Return a resolved PluginCapabilityManifest
+ */
+import { type PluginCapability, type PluginCapabilityManifest, type PluginManifestV2 } from './types.js';
+import { type PluginTrustTier } from './trust.js';
+/**
+ * resolveCapabilityManifest — Parse and resolve the capability manifest for a
+ * plugin, applying the runtime's capability policy and trust-tier constraints.
+ *
+ * Evaluation order:
+ *   1. Unknown capability strings are filtered out (warn + ignore).
+ *   2. Trust-tier constraints are applied — high-risk capabilities blocked
+ *      unless the plugin has the `trusted` tier.
+ *   3. The runtime capability policy callback is applied to the remaining set.
+ *
+ * @param pluginName - Plugin name (for logging).
+ * @param manifest   - The raw plugin manifest (may have `capabilities` array).
+ * @param policy     - Capability grant/deny callback. Defaults to permissive.
+ * @param trustTier  - Effective trust tier for this plugin. Defaults to 'untrusted'.
+ * @returns A fully-resolved PluginCapabilityManifest.
+ */
+export declare function resolveCapabilityManifest(pluginName: string, manifest: PluginManifestV2, policy?: (name: string, cap: PluginCapability) => boolean, trustTier?: PluginTrustTier): PluginCapabilityManifest;
+/**
+ * isHighRiskCapability — Returns whether a capability is classified as high-risk.
+ * High-risk capabilities require the `trusted` tier to be granted.
+ */
+export declare function isHighRiskCapability(capability: PluginCapability): boolean;
+/**
+ * hasCapability — Returns whether a plugin has been granted a specific
+ * capability after manifest resolution.
+ */
+export declare function hasCapability(manifest: PluginCapabilityManifest, capability: PluginCapability): boolean;
+/**
+ * validateManifestV2 — Light validation of the PluginManifestV2 shape.
+ * Returns null on success or an error string on failure.
+ */
+export declare function validateManifestV2(manifest: unknown): string | null;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/_internal/platform/runtime/plugins/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/plugins/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,eAAe,EAA6B,MAAM,YAAY,CAAC;AAkB7E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,KAAK,OAAuB,EACxE,SAAS,GAAE,eAA6B,GACvC,wBAAwB,CAwD1B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,gBAAgB,GAAG,OAAO,CAE1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,wBAAwB,EAClC,UAAU,EAAE,gBAAgB,GAC3B,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CA4BnE"}