@inharness-ai/claude4spec 1.0.21 → 1.0.23

package/dist/server/core/plugin-host/overlay-loader.js

@@ -0,0 +1,243 @@
+/**
+ * M33 — project-local plugin overlay loader.
+ *
+ * The second of the two M33 tracks (the first being the process-global
+ * `loadWorkspacePlugins`). This one loads plugins committed into a repo at
+ * `<cwd>/.claude4spec/plugins/<pkg>/` and builds a per-`ProjectContext`
+ * `ProjectPluginOverlay`. Because a `git clone` brings this code with it,
+ * loading is gated by `trustProjectPlugins` — the CALLER decides trust and only
+ * invokes `loadProjectOverlay` when trusted; `enumerateOverlayPackages` is the
+ * code-free probe used to drive the trust prompt.
+ *
+ * Per package, each step is isolated in its own try/catch so one bad plugin is
+ * skipped — never failing the project build:
+ *   1. Resolve entry  — package.json main/module/exports, else index.{js,mjs}.
+ *   2. Dynamic import — `import(pathToFileURL(entry))` (native ESM).
+ *   3. Validate+gate  — shared with the workspace loader (hostApiVersion+engines).
+ *   4. Lower entities — `lowerEntityContribution`, enforcing within-overlay
+ *      type uniqueness (second duplicate → PLUGIN_TYPE_CONFLICT, rejected).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { entryCacheBust } from './cache-bust.js';
+import { extractManifest, gateManifest, isValidManifestShape, } from './loader.js';
+import { lowerEntityContribution, validateWritingStyle } from './manifest-adapter.js';
+const defaultImporter = (specifier) => import(specifier);
+/** Absolute path to a project's local plugins directory. */
+export function projectPluginsDir(cwd) {
+    return path.join(cwd, '.claude4spec', 'plugins');
+}
+/**
+ * Package directory names under `<cwd>/.claude4spec/plugins/`. Pure FS read — no
+ * code runs — so it is safe to call before the trust decision (drives the prompt
+ * and the untrusted-layer diagnostics).
+ */
+export function enumerateOverlayPackages(cwd) {
+    const dir = projectPluginsDir(cwd);
+    let entries;
+    try {
+        if (!fs.existsSync(dir))
+            return [];
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+/** True when the project ships at least one local plugin package. */
+export function hasProjectPlugins(cwd) {
+    return enumerateOverlayPackages(cwd).length > 0;
+}
+/**
+ * Resolve a package.json `exports` field to a relative entry path. Handles the
+ * common shapes: a bare string, the `"."` subpath, and a conditions object
+ * (`{ import, default, require, node }`) at either the top level or under `"."`.
+ * Returns the first string match (preferring ESM `import`/`default`), or
+ * undefined if no string entry is reachable (caller falls back to module/main).
+ * Exported so the workspace-tier frontend resolver reuses the same condition
+ * handling for a plugin's `exports['./frontend']` (see `frontend-assets.ts`).
+ */
+export function resolveExportsEntry(exp) {
+    if (typeof exp === 'string')
+        return exp;
+    if (!exp || typeof exp !== 'object')
+        return undefined;
+    const obj = exp;
+    // Subpath map: drill into "." first, then treat the whole object as conditions.
+    const dot = obj['.'];
+    if (typeof dot === 'string')
+        return dot;
+    const conditions = (dot && typeof dot === 'object' ? dot : obj);
+    for (const key of ['import', 'module', 'default', 'node', 'require']) {
+        const v = conditions[key];
+        if (typeof v === 'string')
+            return v;
+    }
+    return undefined;
+}
+/** Resolve the ESM entry file of a package directory. Returns null if none found. */
+function resolveEntry(pkgDir) {
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (fs.existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+            const rel = resolveExportsEntry(pkg.exports) ?? pkg.module ?? pkg.main;
+            if (rel) {
+                const abs = path.resolve(pkgDir, rel);
+                if (fs.existsSync(abs))
+                    return abs;
+            }
+        }
+        catch {
+            /* fall through to index.* probing */
+        }
+    }
+    for (const candidate of ['index.js', 'index.mjs', 'index.cjs']) {
+        const abs = path.join(pkgDir, candidate);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+/**
+ * Load and validate the trusted project-local overlay for `cwd`. The caller must
+ * have already confirmed `trustProjectPlugins === true`; this function executes
+ * project-committed code.
+ */
+export async function loadProjectOverlay(cwd, importer = defaultImporter) {
+    const records = [];
+    const modules = new Map();
+    const originByType = new Map();
+    const writingStyles = [];
+    // M33: non-entity capabilities of trusted project-local plugins. An
+    // entity-less plugin (commands/settings only) still produces these.
+    const settingsSections = [];
+    const commands = [];
+    const teardowns = [];
+    for (const pkg of enumerateOverlayPackages(cwd)) {
+        const pkgDir = path.join(projectPluginsDir(cwd), pkg);
+        const origin = path.join('.claude4spec', 'plugins', pkg);
+        const base = { package: pkg, status: 'loaded', layer: 'overlay', trust: 'trusted', origin };
+        const entry = resolveEntry(pkgDir);
+        if (!entry) {
+            const reason = 'no resolvable ESM entry (package.json main/module/exports or index.{js,mjs,cjs})';
+            console.warn(`[overlay-loader] PLUGIN_INVALID_MANIFEST ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason });
+            continue;
+        }
+        let mod;
+        try {
+            mod = await importer(pathToFileURL(entry).href + entryCacheBust(entry));
+        }
+        catch (err) {
+            const reason = err.message;
+            console.warn(`[overlay-loader] PLUGIN_IMPORT_FAILED ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_IMPORT_FAILED', reason });
+            continue;
+        }
+        const manifest = extractManifest(mod);
+        if (!isValidManifestShape(manifest)) {
+            const reason = 'package does not export a valid PluginManifest (manifest/default)';
+            console.warn(`[overlay-loader] PLUGIN_INVALID_MANIFEST ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason });
+            continue;
+        }
+        const gate = gateManifest(manifest);
+        if (gate) {
+            console.warn(`[overlay-loader] ${gate.code} ${pkg}: ${gate.reason}`);
+            records.push({
+                ...base,
+                status: gate.status,
+                code: gate.code,
+                reason: gate.reason,
+                migration: gate.migration,
+                manifestName: manifest.name,
+                manifestVersion: manifest.version,
+            });
+            continue;
+        }
+        // Lower contributions (entities + styles) before committing — a throw on
+        // either fails the whole plugin atomically.
+        let lowered;
+        let styles;
+        try {
+            lowered = (manifest.contributes?.entities ?? []).map(lowerEntityContribution);
+            styles = (manifest.contributes?.writingStyles ?? []).map(validateWritingStyle);
+        }
+        catch (err) {
+            const reason = err.message;
+            console.warn(`[overlay-loader] PLUGIN_INVALID_MANIFEST ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_INVALID_MANIFEST', reason });
+            continue;
+        }
+        // Enforce within-overlay (same-layer) type uniqueness.
+        const conflict = lowered.find((m) => modules.has(m.type));
+        if (conflict) {
+            const reason = `type "${conflict.type}" already provided by another project-local plugin (origin ${originByType.get(conflict.type)})`;
+            console.warn(`[overlay-loader] PLUGIN_TYPE_CONFLICT ${pkg}: ${reason}`);
+            records.push({ ...base, status: 'failed', code: 'PLUGIN_TYPE_CONFLICT', reason });
+            continue;
+        }
+        for (const m of lowered) {
+            modules.set(m.type, m);
+            originByType.set(m.type, origin);
+        }
+        writingStyles.push(...styles);
+        // M33: capture non-entity capabilities + teardown of this trusted plugin.
+        if ((manifest.contributes?.settings ?? []).length > 0) {
+            settingsSections.push({
+                name: manifest.name,
+                version: manifest.version,
+                fields: manifest.contributes.settings,
+            });
+        }
+        commands.push(...(manifest.contributes?.commands ?? []));
+        if (typeof manifest.onUnregister === 'function') {
+            const fn = manifest.onUnregister.bind(manifest);
+            teardowns.push(fn);
+        }
+        else {
+            console.warn(`[overlay-loader] plugin "${manifest.name}" — required slot onUnregister is missing; using a no-op teardown`);
+        }
+        records.push({
+            ...base,
+            manifestName: manifest.name,
+            manifestVersion: manifest.version,
+            contributedTypes: lowered.map((m) => m.type),
+        });
+    }
+    // Node's ESM registry caches modules by URL — a true unload is not possible.
+    // dispose() runs each plugin's `onUnregister` (M33 teardown) then
+    // drops the host-side references (mirrors clearMcpFactories); a rebuild
+    // re-imports (cached) fresh manifests. Stateful native handles, if a plugin
+    // opens any, are the plugin's own teardown responsibility.
+    const dispose = () => {
+        for (const teardown of teardowns) {
+            try {
+                teardown();
+            }
+            catch (err) {
+                console.warn(`[overlay-loader] onUnregister threw during dispose: ${err.message}`);
+            }
+        }
+        modules.clear();
+        originByType.clear();
+    };
+    // No capabilities at all ⇒ no overlay host layer, but a plugin may still have
+    // contributed writing styles — return those so the caller can push them.
+    // M33: an entity-less plugin with only settings/commands DOES produce
+    // an overlay so the host surfaces those capabilities (axis B).
+    if (modules.size === 0 && settingsSections.length === 0 && commands.length === 0) {
+        return { overlay: undefined, records, writingStyles, dispose };
+    }
+    const overlay = {
+        listLocal: () => Array.from(modules.values()),
+        origin: (type) => originByType.get(type) ?? '',
+        listSettings: () => settingsSections,
+        listCommands: () => commands,
+    };
+    return { overlay, records, writingStyles, dispose };
+}
+//# sourceMappingURL=overlay-loader.js.map

package/dist/server/core/plugin-host/overlay-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-loader.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/overlay-loader.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/plugin-watcher.d.ts

@@ -0,0 +1,41 @@
+/**
+ * M33 — plugin-pool hot-reload watcher.
+ *
+ * The main `PagesWatcher` is rooted OUTSIDE `.claude4spec/`, so plugin sources
+ * are watched by this dedicated watcher instead. It is the *mechanism only* —
+ * the reload pipeline (cache-bust import → onUnregister old → register new →
+ * invalidate ProjectContext → broadcast) is supplied by the caller via
+ * `onReload`. There is deliberately no projection store (no `byPath` map, no
+ * SQLite): the live `PluginRegistry` (base) + `ProjectPluginOverlay` (overlay)
+ * ARE the index (divergence from M29 — only the watcher is reused).
+ *
+ * Two callers wire it differently:
+ *   - overlay: one watcher per `ProjectContext` over `<cwd>/.claude4spec/plugins/`,
+ *     mounted only behind the `trustProjectPlugins` gate; closed on dispose.
+ *   - base: one process-global watcher over the resolved workspace package dirs.
+ */
+export type PluginWatcherCallback = (changedPaths: string[]) => void;
+export declare class PluginWatcher {
+    private readonly roots;
+    private readonly onReload;
+    private readonly debounceMs;
+    private watcher;
+    private timer;
+    private pending;
+    private suppressUntil;
+    /**
+     * @param roots   absolute directories to watch (empty ⇒ `start()` is a no-op).
+     * @param onReload invoked (debounced) with the de-duplicated changed paths.
+     */
+    constructor(roots: string[], onReload: PluginWatcherCallback, debounceMs?: number);
+    start(): void;
+    /**
+     * Call BEFORE a reload-initiated write into a watched dir so the resulting
+     * chokidar event does not re-trigger the pipeline (reload → write → reload).
+     * Keyed by absolute path.
+     */
+    suppress(absPath: string): void;
+    private queue;
+    private flush;
+    close(): Promise<void>;
+}

package/dist/server/core/plugin-host/plugin-watcher.js

@@ -0,0 +1,95 @@
+/**
+ * M33 — plugin-pool hot-reload watcher.
+ *
+ * The main `PagesWatcher` is rooted OUTSIDE `.claude4spec/`, so plugin sources
+ * are watched by this dedicated watcher instead. It is the *mechanism only* —
+ * the reload pipeline (cache-bust import → onUnregister old → register new →
+ * invalidate ProjectContext → broadcast) is supplied by the caller via
+ * `onReload`. There is deliberately no projection store (no `byPath` map, no
+ * SQLite): the live `PluginRegistry` (base) + `ProjectPluginOverlay` (overlay)
+ * ARE the index (divergence from M29 — only the watcher is reused).
+ *
+ * Two callers wire it differently:
+ *   - overlay: one watcher per `ProjectContext` over `<cwd>/.claude4spec/plugins/`,
+ *     mounted only behind the `trustProjectPlugins` gate; closed on dispose.
+ *   - base: one process-global watcher over the resolved workspace package dirs.
+ */
+import chokidar from 'chokidar';
+import path from 'node:path';
+const DEFAULT_DEBOUNCE_MS = 300;
+const SUPPRESS_WINDOW_MS = 600;
+export class PluginWatcher {
+    roots;
+    onReload;
+    debounceMs;
+    watcher = null;
+    timer = null;
+    pending = new Set();
+    suppressUntil = new Map();
+    /**
+     * @param roots   absolute directories to watch (empty ⇒ `start()` is a no-op).
+     * @param onReload invoked (debounced) with the de-duplicated changed paths.
+     */
+    constructor(roots, onReload, debounceMs = DEFAULT_DEBOUNCE_MS) {
+        this.roots = roots;
+        this.onReload = onReload;
+        this.debounceMs = debounceMs;
+    }
+    start() {
+        if (this.roots.length === 0 || this.watcher)
+            return;
+        this.watcher = chokidar.watch(this.roots, {
+            ignoreInitial: true,
+            awaitWriteFinish: { stabilityThreshold: 80, pollInterval: 20 },
+        });
+        const onEvent = (p) => this.queue(p);
+        this.watcher.on('add', onEvent);
+        this.watcher.on('change', onEvent);
+        this.watcher.on('unlink', onEvent);
+        this.watcher.on('addDir', onEvent);
+        this.watcher.on('unlinkDir', onEvent);
+    }
+    /**
+     * Call BEFORE a reload-initiated write into a watched dir so the resulting
+     * chokidar event does not re-trigger the pipeline (reload → write → reload).
+     * Keyed by absolute path.
+     */
+    suppress(absPath) {
+        this.suppressUntil.set(path.resolve(absPath), Date.now() + SUPPRESS_WINDOW_MS);
+    }
+    queue(absPath) {
+        const resolved = path.resolve(absPath);
+        const until = this.suppressUntil.get(resolved);
+        if (until && Date.now() < until) {
+            this.suppressUntil.delete(resolved);
+            return;
+        }
+        this.pending.add(resolved);
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => this.flush(), this.debounceMs);
+    }
+    flush() {
+        this.timer = null;
+        if (this.pending.size === 0)
+            return;
+        const paths = [...this.pending];
+        this.pending.clear();
+        try {
+            this.onReload(paths);
+        }
+        catch (err) {
+            console.warn('[plugin-watcher] onReload threw:', err.message);
+        }
+    }
+    async close() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pending.clear();
+        await this.watcher?.close();
+        this.watcher = null;
+    }
+}
+//# sourceMappingURL=plugin-watcher.js.map

package/dist/server/core/plugin-host/plugin-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-watcher.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/plugin-watcher.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/project-host.d.ts

@@ -5,22 +5,28 @@
  */
 import type { Database } from 'better-sqlite3';
 import type { McpServerInstance } from '@inharness-ai/agent-adapters';
-import type { BackendModule, MountContext, PluginRegistry, ProjectPluginHost } from './types.js';
+import type { BackendModule, MountContext, PluginRegistry, ProjectPluginHost, ProjectPluginOverlay, ShadowedType } from './types.js';
 import type { PluginActivationState } from '../../../shared/plugin-host/types.js';
+import type { PluginCommandContribution, PluginSettingsSection } from '../../../shared/plugin-host/manifest.js';
 import type { EntityDiff, RestoreContext, RestoreResult, SerializeContext, SnapshotData } from '../../serialization/types.js';
 export declare class ProjectPluginHostImpl implements ProjectPluginHost {
     private readonly registry;
+    private readonly overlay?;
     private activeTypes;
     private unknownTypes;
     private mcpServerFactories;
     private entityServices;
-    constructor(registry: PluginRegistry, activeWhitelist: string[] | null | undefined);
+    private readonly overlayModules;
+    constructor(registry: PluginRegistry, activeWhitelist: string[] | null | undefined, overlay?: ProjectPluginOverlay | undefined);
     listAvailable(): BackendModule[];
     listEntities(): BackendModule[];
+    listSettings(): PluginSettingsSection[];
+    listCommands(): PluginCommandContribution[];
     getEntity(type: string): BackendModule | null;
     getAvailable(type: string): BackendModule | null;
     isActive(type: string): boolean;
     partition(): PluginActivationState;
+    shadowReport(): ShadowedType[];
     mountBackend(ctx: MountContext): void;
     registerMcpServer(name: string, factory: () => McpServerInstance): void;
     buildMcpServers(): Array<{

package/dist/server/core/plugin-host/project-host.js

@@ -6,21 +6,33 @@
 import { diffEntity, restoreEntity, snapshotEntity } from '../../serialization/snapshot.js';
 export class ProjectPluginHostImpl {
     registry;
+    overlay;
     activeTypes = null; // null = all active
     unknownTypes = [];
     mcpServerFactories = new Map();
     entityServices = new Map();
-    constructor(registry, activeWhitelist) {
+    // Project-local modules of THIS context, keyed by type. Empty when
+    // `overlay === undefined` (parity with the base-only case).
+    overlayModules = new Map();
+    constructor(registry, activeWhitelist, overlay) {
         this.registry = registry;
+        this.overlay = overlay;
+        // Effective pool = base ∪ overlay. Overlay wins on cross-layer collision
+        // (shadow) — `getAvailable`/`listAvailable` consult the overlay first.
+        for (const m of overlay?.listLocal() ?? []) {
+            this.overlayModules.set(m.type, m);
+        }
         if (activeWhitelist == null) {
             this.activeTypes = null;
             this.unknownTypes = [];
             return;
         }
+        // The whitelist is applied to the merged pool, not the base alone — an
+        // overlay type is activatable exactly like a base type.
         const active = new Set();
         const unknown = [];
         for (const type of activeWhitelist) {
-            if (this.registry.getAvailable(type))
+            if (this.getAvailable(type))
                 active.add(type);
             else
                 unknown.push(type);
@@ -29,21 +41,49 @@ export class ProjectPluginHostImpl {
         this.unknownTypes = unknown;
     }
     listAvailable() {
-        return this.registry.listAvailable();
+        // Merge base + overlay; overlay shadows a same-typed base module.
+        const merged = new Map();
+        for (const m of this.registry.listAvailable())
+            merged.set(m.type, m);
+        for (const [type, m] of this.overlayModules)
+            merged.set(type, m);
+        return Array.from(merged.values()).sort((a, b) => a.displayOrder - b.displayOrder);
     }
     listEntities() {
         return this.listAvailable().filter((m) => this.isActive(m.type));
     }
+    listSettings() {
+        // Axis B (pool + trust), NOT axis A: deliberately unfiltered by
+        // `config.entities`. Base records are always loaded+trusted; the overlay is
+        // only constructed on the trusted path, so its sections are trusted too.
+        // Overlay shadows base on a name collision (parity with type shadowing).
+        const byName = new Map();
+        for (const r of this.registry.listPluginRecords()) {
+            if (r.settings.length > 0) {
+                byName.set(r.name, { name: r.name, version: r.version, fields: r.settings });
+            }
+        }
+        for (const section of this.overlay?.listSettings() ?? []) {
+            byName.set(section.name, section);
+        }
+        return Array.from(byName.values());
+    }
+    listCommands() {
+        // Same two-axis rationale as listSettings(): pool + trust, not entities.
+        const base = this.registry.listPluginRecords().flatMap((r) => r.commands);
+        return [...base, ...(this.overlay?.listCommands() ?? [])];
+    }
     getEntity(type) {
         if (!this.isActive(type))
             return null;
-        return this.registry.getAvailable(type);
+        return this.getAvailable(type);
     }
     getAvailable(type) {
-        return this.registry.getAvailable(type);
+        // Overlay shadows base on cross-layer collision.
+        return this.overlayModules.get(type) ?? this.registry.getAvailable(type) ?? null;
     }
     isActive(type) {
-        if (!this.registry.getAvailable(type))
+        if (!this.getAvailable(type))
             return false;
         if (this.activeTypes == null)
             return true;
@@ -56,6 +96,16 @@ export class ProjectPluginHostImpl {
             .map((m) => m.type);
         return { active, inactive, unknown: [...this.unknownTypes] };
     }
+    shadowReport() {
+        const out = [];
+        for (const type of this.overlayModules.keys()) {
+            // Cross-layer collision: the overlay type also exists in the base layer.
+            if (this.registry.getAvailable(type)) {
+                out.push({ type, overlayOrigin: this.overlay?.origin(type) ?? '' });
+            }
+        }
+        return out;
+    }
     mountBackend(ctx) {
         // A throwing plugin mount propagates — M31 turns it into a per-project
         // build failure (500 PROJECT_BUILD_FAILED), never a process crash.

package/dist/server/core/plugin-host/project-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-host.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/project-host.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project-host.js","sourceRoot":"","sources":["../../../../src/server/core/plugin-host/project-host.ts"],"names":[],"mappings":"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"}

package/dist/server/core/plugin-host/registry.d.ts

@@ -3,12 +3,36 @@
  * singleton — the registry is immutable after `registerAllPlugins(registry)`
  * runs at process start, and `consolidate(config.entities)` is a pure factory
  * producing one ProjectPluginHost per project context.
+ *
+ * M33: the base layer is no longer process-immutable — the hot-reload
+ * pipeline mutates it via `registerPlugin` / `unregisterPlugin` and then
+ * invalidates dependent `ProjectContext`s (axis B). The registry additionally
+ * retains a per-plugin {@link RegisteredPluginRecord} so the host can surface
+ * non-entity capabilities (settings/commands) and the reload pipeline can call
+ * the old version's `onUnregister` before re-registering.
  */
-import type { BackendModule, PluginRegistry, ProjectPluginHost } from './types.js';
+import type { BackendModule, PluginRegistry, ProjectPluginHost, ProjectPluginOverlay, RegisteredPluginRecord } from './types.js';
+import type { PluginManifest, WritingStyleContribution } from '../../../shared/plugin-host/manifest.js';
 export declare class PluginRegistryImpl implements PluginRegistry {
     private modules;
+    private plugins;
     registerEntityModule(module: BackendModule): void;
+    /**
+     * Validate a manifest's shape and lower every contribution WITHOUT mutating
+     * the registry. Throws `PluginManifestError` on any structural problem (the
+     * loader/reload pipeline catches it). The hot-reload pipeline calls this
+     * BEFORE tearing the old version down, so a structurally-broken new version
+     * never leaves the pool missing a type ("old stays").
+     */
+    private validateAndLower;
+    validatePlugin(manifest: PluginManifest): void;
+    registerPlugin(manifest: PluginManifest): void;
+    unregisterPlugin(name: string): void;
+    listPluginRecords(): RegisteredPluginRecord[];
+    listWritingStyles(): WritingStyleContribution[];
     listAvailable(): BackendModule[];
     getAvailable(type: string): BackendModule | null;
-    consolidate(activeWhitelist: string[] | null | undefined): ProjectPluginHost;
+    consolidate(config: {
+        entities?: string[];
+    } | null | undefined, overlay?: ProjectPluginOverlay): ProjectPluginHost;
 }