@zhin.js/runtime 1.0.4 → 1.0.6

package/lib/config-composer.js

@@ -116,10 +116,36 @@ export class ConfigComposer {
         });
     }
 }
+const FRAMEWORK_ROLE_SCHEMA = Object.freeze({
+    master: Object.freeze({
+        type: ['string', 'number'],
+        description: 'Endpoint owner (framework-level master role)',
+    }),
+    trusted: Object.freeze({
+        type: 'array',
+        items: Object.freeze({ type: ['string', 'number'] }),
+        description: 'Trusted user ID list (framework-level trusted role)',
+    }),
+});
+function hasArrayEndpoints(props) {
+    const ep = props.endpoints;
+    if (!ep || typeof ep !== 'object')
+        return false;
+    return ep.type === 'array';
+}
 async function composeNode(node, ownSchemas) {
     const own = await readOwnSchema(node);
     ownSchemas.set(node.id, own);
     const properties = { ...schemaProperties(own) };
+    // Adapter plugins (schemas declaring array-typed `endpoints`) get
+    // framework-level `master` / `trusted` injected when not already declared.
+    if (hasArrayEndpoints(properties)) {
+        for (const [key, schema] of Object.entries(FRAMEWORK_ROLE_SCHEMA)) {
+            if (!Object.hasOwn(properties, key)) {
+                properties[key] = schema;
+            }
+        }
+    }
     for (const child of node.children) {
         if (Object.hasOwn(properties, child.instanceKey)) {
             throw new ConfigSchemaCollisionError(node.id, child.instanceKey);

package/lib/convention-capability-delta.d.ts

@@ -0,0 +1,26 @@
+import { type CapabilityId, type FeatureId, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { FallbackInvalidation } from './invalidation-planner.js';
+import type { ModuleRuntime } from './module-runtime.js';
+import type { RuntimeGenerationModel } from './runtime-generation.js';
+export type CapabilityDelta = ReadonlyMap<FeatureId, ReadonlySet<CapabilityId>>;
+export interface ConventionCapabilityDelta {
+    readonly capabilities: CapabilityDelta;
+    readonly unresolved: readonly FallbackInvalidation[];
+}
+/**
+ * Resolves unowned filesystem paths through mounted Feature conventions.
+ * Conventions are asked to enumerate sources only: definition modules stay
+ * untouched until SlotGenerationPreparer commits the selected delta.
+ */
+export declare class ConventionCapabilityDeltaResolver {
+    #private;
+    private readonly model;
+    private readonly snapshot;
+    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, snapshot: RuntimeSnapshot);
+    resolve(fallbacks: readonly FallbackInvalidation[], selected: readonly CapabilityId[]): Promise<ConventionCapabilityDelta>;
+}
+export declare function capabilityDeltaFromSlots(snapshot: RuntimeSnapshot, selected: readonly CapabilityId[]): CapabilityDelta;
+export declare function mergeCapabilityDeltas(...deltas: readonly CapabilityDelta[]): CapabilityDelta;
+export declare function filterCapabilityDelta(delta: CapabilityDelta, predicate: (owner: PluginId) => boolean): CapabilityDelta;
+export declare function capabilityDeltaIds(delta: CapabilityDelta): readonly CapabilityId[];
+export declare function capabilityOwner(id: CapabilityId): PluginId;

package/lib/convention-capability-delta.js

@@ -0,0 +1,143 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { capabilityId } from '@zhin.js/plugin-runtime';
+import { NodeDiscoveryHost } from './node-discovery-host.js';
+/**
+ * Resolves unowned filesystem paths through mounted Feature conventions.
+ * Conventions are asked to enumerate sources only: definition modules stay
+ * untouched until SlotGenerationPreparer commits the selected delta.
+ */
+export class ConventionCapabilityDeltaResolver {
+    model;
+    snapshot;
+    #host;
+    constructor(modules, model, snapshot) {
+        this.model = model;
+        this.snapshot = snapshot;
+        this.#host = new NodeDiscoveryHost(modules);
+    }
+    async resolve(fallbacks, selected) {
+        const capabilities = new Map();
+        const unresolved = [];
+        const cache = new Map();
+        for (const fallback of fallbacks) {
+            let claimed = false;
+            for (const owner of fallback.owners) {
+                for (const [feature, provider] of this.model.providers) {
+                    const roots = (this.model.rootsByFeature.get(feature) ?? [])
+                        .filter((root) => root.owner === owner && contains(root.packageRoot, fallback.source));
+                    for (const root of roots) {
+                        const discovered = await this.#discover(cache, provider, root);
+                        for (const candidate of discovered) {
+                            if (candidate.source !== fallback.source)
+                                continue;
+                            const ids = capabilities.get(feature) ?? new Set();
+                            ids.add(candidate.id);
+                            capabilities.set(feature, ids);
+                            claimed = true;
+                        }
+                    }
+                }
+            }
+            if (!claimed)
+                unresolved.push(fallback);
+        }
+        await this.#discoverMoves(cache, capabilities, selected);
+        return Object.freeze({
+            capabilities: freezeCapabilityDelta(capabilities),
+            unresolved: Object.freeze(unresolved),
+        });
+    }
+    async #discoverMoves(cache, capabilities, selected) {
+        for (const id of selected) {
+            const slot = this.snapshot.capabilities.get(id);
+            if (!slot || slot.origin === 'setup')
+                continue;
+            const provider = this.model.providers.get(slot.feature);
+            if (!provider)
+                continue;
+            const roots = (this.model.rootsByFeature.get(slot.feature) ?? [])
+                .filter((root) => root.owner === slot.owner && contains(root.packageRoot, slot.source));
+            for (const root of roots) {
+                const discovered = await this.#discover(cache, provider, root);
+                if (discovered.some((candidate) => candidate.source === slot.source))
+                    continue;
+                for (const candidate of discovered) {
+                    if (this.snapshot.capabilities.has(candidate.id))
+                        continue;
+                    const ids = capabilities.get(slot.feature) ?? new Set();
+                    ids.add(candidate.id);
+                    capabilities.set(slot.feature, ids);
+                }
+            }
+        }
+    }
+    async #discover(cache, provider, root) {
+        const key = `${provider.id}\0${root.owner}\0${root.packageRoot}`;
+        const existing = cache.get(key);
+        if (existing)
+            return existing;
+        const discovered = [];
+        const context = { ...root, host: this.#host };
+        for (const convention of provider.authoring.conventions) {
+            for await (const source of convention.discover(context)) {
+                discovered.push(Object.freeze({
+                    source: resolve(source.source),
+                    id: capabilityId(root.owner, provider.id, source.localName),
+                }));
+            }
+        }
+        const frozen = Object.freeze(discovered);
+        cache.set(key, frozen);
+        return frozen;
+    }
+}
+export function capabilityDeltaFromSlots(snapshot, selected) {
+    const result = new Map();
+    for (const id of selected) {
+        const slot = snapshot.capabilities.get(id);
+        if (!slot)
+            continue;
+        const ids = result.get(slot.feature) ?? new Set();
+        ids.add(id);
+        result.set(slot.feature, ids);
+    }
+    return freezeCapabilityDelta(result);
+}
+export function mergeCapabilityDeltas(...deltas) {
+    const result = new Map();
+    for (const delta of deltas) {
+        for (const [feature, ids] of delta) {
+            const merged = result.get(feature) ?? new Set();
+            for (const id of ids)
+                merged.add(id);
+            result.set(feature, merged);
+        }
+    }
+    return freezeCapabilityDelta(result);
+}
+export function filterCapabilityDelta(delta, predicate) {
+    const result = new Map();
+    for (const [feature, ids] of delta) {
+        for (const id of ids) {
+            if (!predicate(capabilityOwner(id)))
+                continue;
+            const filtered = result.get(feature) ?? new Set();
+            filtered.add(id);
+            result.set(feature, filtered);
+        }
+    }
+    return freezeCapabilityDelta(result);
+}
+export function capabilityDeltaIds(delta) {
+    return Object.freeze([...delta.values()].flatMap((ids) => [...ids]));
+}
+export function capabilityOwner(id) {
+    return id.slice(0, id.indexOf('\0'));
+}
+function freezeCapabilityDelta(delta) {
+    return new Map([...delta].map(([feature, ids]) => [feature, new Set(ids)]));
+}
+function contains(root, source) {
+    const path = relative(root, resolve(source));
+    return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+}

package/lib/environment-store.d.ts

@@ -37,6 +37,12 @@ export declare class EnvSchemaParseError extends Error {
     readonly owner: PluginId;
     constructor(owner: PluginId, message: string);
 }
+/**
+ * The PluginGraph owner path is the sole namespace for Plugin overlays.
+ * Package names and bare instance keys are deliberately not accepted as
+ * aliases: a layer for `root/a` can flow only to `root/a` and descendants.
+ */
+export declare function environmentOwnerPath(owner: PluginId): readonly PluginId[];
 export declare function defineEnvSchema<T>(schema: EnvSchema<T>): Readonly<EnvSchema<T>>;
 export declare function defineEnvironmentLayers(layers?: EnvironmentLayers): Readonly<EnvironmentLayers>;
 export declare function createEnvStore(owner: PluginId, environment: RuntimeEnvironment, layers?: EnvironmentLayers): EnvStore;

package/lib/environment-store.js

@@ -18,6 +18,19 @@ export class EnvSchemaParseError extends Error {
         this.name = 'EnvSchemaParseError';
     }
 }
+/**
+ * The PluginGraph owner path is the sole namespace for Plugin overlays.
+ * Package names and bare instance keys are deliberately not accepted as
+ * aliases: a layer for `root/a` can flow only to `root/a` and descendants.
+ */
+export function environmentOwnerPath(owner) {
+    const value = String(owner);
+    if (!/^root(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(value)) {
+        throw new TypeError(`Invalid Plugin environment owner: ${owner}`);
+    }
+    const segments = value.split('/');
+    return Object.freeze(segments.map((_, index) => segments.slice(0, index + 1).join('/')));
+}
 export function defineEnvSchema(schema) {
     const secretKeys = Object.freeze([...(schema.secretKeys ?? [])]);
     for (const key of secretKeys)
@@ -35,7 +48,10 @@ export function defineEnvironmentLayers(layers = {}) {
         return [name, copySource(source, `environment ${name}`)];
     }));
     const plugins = Object.fromEntries(Object.entries(layers.plugins ?? {}).map(([owner, source]) => {
-        if (!/^root(?:\/[a-z0-9][a-z0-9-]*)*$/u.test(owner)) {
+        try {
+            environmentOwnerPath(owner);
+        }
+        catch {
             throw new TypeError(`Invalid Plugin environment overlay owner: ${owner}`);
         }
         return [owner, copySource(source, `Plugin ${owner}`)];
@@ -61,7 +77,7 @@ export class EnvStoreFactory {
         const source = {};
         applyLayer(source, this.#layers.base);
         applyLayer(source, this.#layers.environments?.[this.#environment.name]);
-        for (const ancestor of pluginAncestors(owner)) {
+        for (const ancestor of environmentOwnerPath(owner)) {
             applyLayer(source, this.#layers.plugins?.[ancestor]);
         }
         return new OwnerEnvStore(owner, this.#environment, Object.freeze(source));
@@ -140,10 +156,6 @@ function applyLayer(target, layer) {
             target[key] = value;
     }
 }
-function pluginAncestors(owner) {
-    const segments = owner.split('/');
-    return Object.freeze(segments.map((_, index) => segments.slice(0, index + 1).join('/')));
-}
 function assertEnvironmentKey(key) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) {
         throw new TypeError(`Invalid environment variable name: ${key}`);

package/lib/hmr-coordinator.js

@@ -14,6 +14,7 @@ export class HmrCoordinator {
         if (!this.options.modules.watch) {
             throw new Error('ModuleRuntime does not provide a file watcher');
         }
+        this.#syncWatchRoots();
         this.#unwatch = this.options.modules.watch((source) => {
             void this.enqueue(source).catch(() => undefined);
         });
@@ -79,6 +80,10 @@ export class HmrCoordinator {
                 if (restart)
                     await this.options.onRestartRequired(restart);
                 else {
+                    // reload resolves only after RootController has committed the new
+                    // generation. Read ownership now so failed transactions never make
+                    // newly discovered workspace packages observable to the watcher.
+                    this.#syncWatchRoots();
                     const durationMs = Number((performance.now() - startedAt).toFixed(1));
                     await this.options.onReload?.(plan, durationMs);
                 }
@@ -112,4 +117,7 @@ export class HmrCoordinator {
         for (const waiter of this.#waiters.splice(0))
             waiter.reject(error);
     }
+    #syncWatchRoots() {
+        this.options.modules.updateWatchRoots?.(this.options.ownership().watchRoots());
+    }
 }

package/lib/invalidation-planner.d.ts

@@ -11,10 +11,18 @@ export interface NoInvalidationPlan {
 export interface GenerationInvalidationPlan {
     readonly kind: 'generation';
     readonly changed: readonly string[];
+    /** Manifest sources require a graph and process-boundary check before reload. */
+    readonly manifestSources: readonly string[];
     readonly slots: readonly CapabilityId[];
     readonly subtrees: readonly PluginId[];
+    /** Paths without ownership records; RootRuntime may claim them through a convention. */
+    readonly fallbacks: readonly FallbackInvalidation[];
     readonly reasons: readonly string[];
 }
+export interface FallbackInvalidation {
+    readonly source: string;
+    readonly owners: readonly PluginId[];
+}
 export interface ProcessInvalidationPlan {
     readonly kind: 'process';
     readonly changed: readonly string[];

package/lib/invalidation-planner.js

@@ -24,9 +24,14 @@ export class InvalidationPlanner {
         }
         const slots = new Map();
         const subtrees = new Set();
+        const fallbacks = [];
+        const manifestSources = new Set();
         const reasons = new Set();
         const processReasons = new Set();
         for (const source of changed) {
+            if (basename(source) === 'package.json') {
+                addManifestSource(manifestSources, reasons, source);
+            }
             const affected = unique([source, ...(this.dependencies?.affectedSources(source) ?? [])].map((item) => resolve(item)));
             let matched = false;
             for (const item of affected) {
@@ -37,17 +42,25 @@ export class InvalidationPlanner {
                     if (requiresProcessRestart(record)) {
                         processReasons.add(`Root ${record.role} source changed`);
                     }
+                    else if (record.role === 'manifest') {
+                        // Manifest changes are handled by RootRuntime after it compares
+                        // the current and inspected graphs. Do not turn them into a
+                        // subtree reload here: that would hide concurrent Slot changes.
+                        addManifestSource(manifestSources, reasons, record.source);
+                    }
                     else {
                         applyRecord(record, slots, subtrees, reasons);
                     }
                 }
             }
             // An untracked support module still belongs to the nearest mounted
-            // package. Without an owned importer, subtree replacement is safest.
+            // package. RootRuntime gets the first chance to claim it through a
+            // mounted Feature convention; unresolved paths retain this fallback.
             if (!matched) {
-                for (const owner of this.ownership.ownersForPath(source)) {
-                    subtrees.add(owner);
-                    reasons.add(`untracked support source changed in ${owner}`);
+                const owners = this.ownership.ownersForPath(source);
+                if (owners.length > 0) {
+                    fallbacks.push(Object.freeze({ source, owners }));
+                    reasons.add(`untracked source changed in ${owners.join(', ')}`);
                 }
             }
         }
@@ -60,7 +73,10 @@ export class InvalidationPlanner {
         }
         const roots = collapseSubtrees(subtrees);
         const retainedSlots = [...slots].flatMap(([capability, owner]) => roots.some((root) => isWithin(owner, root)) ? [] : [capability]);
-        if (roots.length === 0 && retainedSlots.length === 0) {
+        if (roots.length === 0
+            && retainedSlots.length === 0
+            && manifestSources.size === 0
+            && fallbacks.length === 0) {
             return Object.freeze({
                 kind: 'none',
                 changed,
@@ -70,12 +86,19 @@ export class InvalidationPlanner {
         return Object.freeze({
             kind: 'generation',
             changed,
+            manifestSources: Object.freeze([...manifestSources]),
             slots: Object.freeze(retainedSlots),
             subtrees: Object.freeze(roots),
+            fallbacks: Object.freeze(fallbacks),
             reasons: Object.freeze([...reasons]),
         });
     }
 }
+function addManifestSource(manifestSources, reasons, source) {
+    const manifest = resolve(source);
+    manifestSources.add(manifest);
+    reasons.add(`Manifest source changed: ${manifest}`);
+}
 function requiresProcessRestart(record) {
     return (record.owner === rootPluginId()
         && (record.role === 'plugin' || record.role === 'schema'));

package/lib/module-runtime.d.ts

@@ -1,5 +1,9 @@
 import type { Dispose } from '@zhin.js/plugin-runtime';
 import type { ClientModuleRequest } from '@zhin.js/feature-kit';
+export interface ModuleWatchRoot {
+    readonly root: string;
+    readonly source: 'workspace' | 'local';
+}
 export interface ModuleRuntime {
     load<T = unknown>(source: string): Promise<T>;
     /** Optional compiler/manifest adapter for browser modules such as Page and Layout. */
@@ -8,6 +12,8 @@ export interface ModuleRuntime {
     affectedSources?(source: string): readonly string[];
     /** True when this adapter cannot invalidate the complete importer closure safely. */
     requiresProcessRestart?(source: string): boolean;
+    /** Replaces the local package roots after a generation commits. */
+    updateWatchRoots?(roots: readonly ModuleWatchRoot[]): void;
     watch?(listener: (source: string) => void): Dispose;
     close(): Promise<void>;
 }

package/lib/native-development-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Dispose } from '@zhin.js/plugin-runtime';
-import type { ModuleRuntime } from './module-runtime.js';
+import type { ModuleRuntime, ModuleWatchRoot } from './module-runtime.js';
 export interface NativeDevelopmentModuleRuntimeOptions {
     readonly projectRoot: string;
     readonly watch?: boolean;
@@ -15,6 +15,7 @@ export declare class NativeDevelopmentModuleRuntime implements ModuleRuntime {
     load<T = unknown>(source: string): Promise<T>;
     invalidate(source: string): void;
     requiresProcessRestart(source: string): boolean;
+    updateWatchRoots(roots: readonly ModuleWatchRoot[]): void;
     watch(listener: (source: string) => void): Dispose;
     close(): Promise<void>;
 }

package/lib/native-development-runtime.js

@@ -20,10 +20,12 @@ export class NativeDevelopmentModuleRuntime {
     #watchEnabled;
     #revisions = new Map();
     #watchers = new Set();
+    #watchRoots;
     #closed = false;
     constructor(options) {
         this.#projectRoot = resolve(options.projectRoot);
         this.#watchEnabled = options.watch ?? true;
+        this.#watchRoots = normalizeWatchRoots([this.#projectRoot]);
     }
     async load(source) {
         this.#assertOpen();
@@ -43,9 +45,12 @@ export class NativeDevelopmentModuleRuntime {
     }
     requiresProcessRestart(source) {
         const normalized = resolve(source);
-        if (!isWithin(this.#projectRoot, normalized))
+        const packageRoot = nearestWatchRoot(this.#watchRoots, normalized);
+        // Installed packages and external paths are intentionally not watched.
+        // The HMR coordinator turns this into a visible process restart reason.
+        if (!packageRoot || isNodeModulesSource(packageRoot, normalized))
             return true;
-        const parts = relative(this.#projectRoot, normalized).split(sep);
+        const parts = relative(packageRoot, normalized).split(sep);
         const capability = parts.findIndex((part) => capabilityRoots.has(part));
         if (capability < 0)
             return isExecutableSource(normalized);
@@ -63,11 +68,23 @@ export class NativeDevelopmentModuleRuntime {
         // entry's zhin-generation, so the importer closure keeps the old code.
         return ['.js', '.json', '.ts'].includes(extname(normalized));
     }
+    updateWatchRoots(roots) {
+        this.#assertOpen();
+        const next = normalizeWatchRoots([
+            this.#projectRoot,
+            ...roots.map((root) => root.root),
+        ]);
+        if (sameRoots(this.#watchRoots, next))
+            return;
+        this.#watchRoots = next;
+        for (const watcher of this.#watchers)
+            watcher.replaceRoots(next);
+    }
     watch(listener) {
         this.#assertOpen();
         if (!this.#watchEnabled)
             return () => undefined;
-        const watcher = new PortableSourceWatcher(this.#projectRoot, listener);
+        const watcher = new PortableSourceWatcher(this.#watchRoots, listener);
         this.#watchers.add(watcher);
         return () => {
             watcher.close();
@@ -103,48 +120,73 @@ export function assertNativeTypeScriptSupport() {
     ].join(' '));
 }
 class PortableSourceWatcher {
-    root;
     listener;
-    #watcher;
+    #watchers = new Set();
     #pollTimer;
     #snapshot;
     #closed = false;
-    constructor(root, listener) {
-        this.root = root;
+    #roots;
+    constructor(roots, listener) {
         this.listener = listener;
-        this.#snapshot = sourceSnapshot(root);
-        this.#startNativeWatcher();
+        this.#roots = normalizeWatchRoots(roots);
+        this.#snapshot = sourceSnapshot(this.#roots);
+        this.#startNativeWatchers();
+    }
+    replaceRoots(roots) {
+        if (this.#closed)
+            return;
+        const next = normalizeWatchRoots(roots);
+        if (sameRoots(this.#roots, next))
+            return;
+        // The root set and polling snapshot change together. Native handles are
+        // replaced afterwards; stale handles are filtered by the committed set.
+        this.#roots = next;
+        this.#snapshot = sourceSnapshot(next);
+        if (!this.#pollTimer)
+            this.#startNativeWatchers();
     }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
-        this.#watcher?.close();
+        this.#closeNativeWatchers();
         if (this.#pollTimer)
             clearInterval(this.#pollTimer);
     }
-    #startNativeWatcher() {
+    #startNativeWatchers() {
+        if (this.#closed || this.#pollTimer)
+            return;
+        const next = new Set();
         try {
-            this.#watcher = watchDirectory(this.root, { recursive: true }, (_event, name) => {
-                if (!name)
-                    return;
-                const source = resolve(this.root, name.toString());
-                if (isWatchedSource(source) && !isIgnoredSource(this.root, source))
-                    this.listener(source);
-            });
-            this.#watcher.on('error', () => this.#startPolling());
+            for (const root of this.#roots) {
+                const watcher = watchDirectory(root, { recursive: true }, (_event, name) => {
+                    if (!name || !this.#roots.includes(root))
+                        return;
+                    const source = resolve(root, name.toString());
+                    if (isWatchedSource(source) && !isIgnoredSource(root, source))
+                        this.listener(source);
+                });
+                watcher.on('error', () => this.#startPolling());
+                next.add(watcher);
+            }
         }
         catch {
+            for (const watcher of next)
+                watcher.close();
             this.#startPolling();
+            return;
         }
+        const previous = this.#watchers;
+        this.#watchers = next;
+        for (const watcher of previous)
+            watcher.close();
     }
     #startPolling() {
         if (this.#closed || this.#pollTimer)
             return;
-        this.#watcher?.close();
-        this.#watcher = undefined;
+        this.#closeNativeWatchers();
         this.#pollTimer = setInterval(() => {
-            const next = sourceSnapshot(this.root);
+            const next = sourceSnapshot(this.#roots);
             const sources = new Set([...this.#snapshot.keys(), ...next.keys()]);
             for (const source of sources) {
                 if (this.#snapshot.get(source) !== next.get(source))
@@ -153,8 +195,13 @@ class PortableSourceWatcher {
             this.#snapshot = next;
         }, 100);
     }
+    #closeNativeWatchers() {
+        for (const watcher of this.#watchers)
+            watcher.close();
+        this.#watchers.clear();
+    }
 }
-function sourceSnapshot(root) {
+function sourceSnapshot(roots) {
     const result = new Map();
     const visit = (directory) => {
         let entries;
@@ -179,7 +226,8 @@ function sourceSnapshot(root) {
             }
         }
     };
-    visit(root);
+    for (const root of roots)
+        visit(root);
     return result;
 }
 function isWatchedSource(source) {
@@ -212,3 +260,16 @@ function isWithin(root, source) {
     const child = relative(root, source);
     return child === '' || (!child.startsWith('..') && !isAbsolute(child));
 }
+function nearestWatchRoot(roots, source) {
+    return roots.find((root) => isWithin(root, source));
+}
+function isNodeModulesSource(root, source) {
+    return relative(root, source).split(sep).some((part) => part === 'node_modules');
+}
+function normalizeWatchRoots(roots) {
+    const sorted = [...new Set(roots.map((root) => resolve(root)))].sort((left, right) => left.length - right.length);
+    return Object.freeze(sorted.filter((root, index) => !sorted.slice(0, index).some((parent) => isWithin(parent, root))));
+}
+function sameRoots(left, right) {
+    return left.length === right.length && left.every((root, index) => root === right[index]);
+}

package/lib/plugin-scope-assembler.d.ts

@@ -41,4 +41,10 @@ export declare class PluginScopeAssembler {
     createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
     generationHandoff(): GenerationHandoff | undefined;
     setupCapabilities(): readonly Readonly<SetupCapabilityRegistration>[];
+    /**
+     * Root resources are process-owned. A Plugin Scope receives only a facade
+     * that translates logical table/job names to its owner namespace. The root
+     * owner deliberately keeps bare names for backward-compatible projects.
+     */
+    private installOwnerScopedHosts;
 }

package/lib/plugin-scope-assembler.js

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { GenerationHandoffStack, Scope, capabilityId, featureId, rootPluginId, } from '@zhin.js/plugin-runtime';
+import { GenerationHandoffStack, Scope, capabilityId, createPluginDatabaseHost, createPluginScheduleHost, databaseHostToken, databaseRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, unwrapPluginDatabaseHost, unwrapPluginScheduleHost, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
 import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
@@ -70,6 +70,8 @@ export class PluginScopeAssembler {
                 config,
             });
         }
+        if (node.parent)
+            this.installOwnerScopedHosts(scope, node.id);
         const config = Object.freeze(this.configResolver(node) ?? {});
         const view = { get: () => config };
         const plugin = Object.freeze({
@@ -196,6 +198,29 @@ export class PluginScopeAssembler {
     setupCapabilities() {
         return Object.freeze([...this.#setupCapabilities.values()]);
     }
+    /**
+     * Root resources are process-owned. A Plugin Scope receives only a facade
+     * that translates logical table/job names to its owner namespace. The root
+     * owner deliberately keeps bare names for backward-compatible projects.
+     */
+    installOwnerScopedHosts(scope, owner) {
+        const database = scope.has(databaseRootHostToken)
+            ? scope.use(databaseRootHostToken)
+            : scope.has(databaseHostToken)
+                ? unwrapPluginDatabaseHost(scope.use(databaseHostToken))
+                : undefined;
+        if (database) {
+            scope.provide(databaseHostToken, createPluginDatabaseHost(owner, database));
+        }
+        const schedule = scope.has(scheduleRootHostToken)
+            ? scope.use(scheduleRootHostToken)
+            : scope.has(scheduleHostToken)
+                ? unwrapPluginScheduleHost(scope.use(scheduleHostToken))
+                : undefined;
+        if (schedule) {
+            scope.provide(scheduleHostToken, createPluginScheduleHost(owner, schedule));
+        }
+    }
 }
 function isWithin(plugin, root) {
     return plugin === root || plugin.startsWith(`${root}/`);

package/lib/root-runtime.js

@@ -16,6 +16,7 @@ import { ProjectGraphService, } from './project-graph.js';
 import { HmrCoordinator } from './hmr-coordinator.js';
 import { RootProcessRestartExecutor, } from './process-restart.js';
 import { SlotGenerationPreparer } from './slot-generation-preparer.js';
+import { capabilityDeltaFromSlots, capabilityDeltaIds, ConventionCapabilityDeltaResolver, filterCapabilityDelta, mergeCapabilityDeltas, } from './convention-capability-delta.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
 import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 import { SubtreeGenerationPreparer, SubtreeTopologyChangedError, } from './subtree-generation-preparer.js';
@@ -114,20 +115,24 @@ export class RootRuntime {
         let prepared;
         let restart;
         const snapshot = await this.controller.reload(plan.subtrees[0] ?? plan.slots[0] ?? rootPluginId(), async (current) => {
-            if (this.#model && this.#isManifestTopologyPlan(plan)) {
+            const resolved = await this.#resolveCapabilityDelta(current, plan);
+            const effective = resolved.plan;
+            if (this.#model && effective.manifestSources.length > 0) {
                 const inspected = await this.#inspectProject();
-                restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, plan.changed);
+                restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, effective.changed);
                 if (restart)
                     return undefined;
-                prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current);
+                prepared = effective.subtrees.includes(rootPluginId())
+                    ? await this.#prepareInspected(current, inspected)
+                    : await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, { ...effective, capabilities: resolved.capabilities });
             }
-            else if (plan.subtrees.length === 0 && plan.slots.length > 0 && this.#model) {
+            else if (effective.subtrees.length === 0 && resolved.capabilities.size > 0 && this.#model) {
                 prepared = await new SlotGenerationPreparer(this.#modules, this.#model)
-                    .prepare(current, plan.slots);
+                    .prepare(current, resolved.capabilities);
             }
-            else if (this.#model && this.#canPrepareSubtrees(plan)) {
+            else if (this.#model && this.#canPrepareSubtrees(effective)) {
                 const inspected = await this.#inspectProject();
-                prepared = await this.#prepareSubtrees(current, inspected, plan.subtrees);
+                prepared = await this.#prepareSubtrees(current, inspected, effective.subtrees);
             }
             else {
                 prepared = await this.#prepare(current);
@@ -140,21 +145,29 @@ export class RootRuntime {
             this.#accept(prepared);
         return snapshot;
     }
-    #isManifestTopologyPlan(plan) {
-        let manifest = false;
-        for (const source of plan.changed) {
-            const records = this.#ownership.recordsFor(source);
-            if (records.some((record) => record.role === 'manifest'))
-                manifest = true;
-            if (records.some((record) => record.role !== 'manifest'))
-                return false;
-        }
-        return manifest;
-    }
     #accept(prepared) {
         this.#ownership = prepared.ownership;
         this.#model = prepared.model;
     }
+    async #resolveCapabilityDelta(current, plan) {
+        const known = capabilityDeltaFromSlots(current, plan.slots);
+        if (!this.#model || (plan.fallbacks.length === 0 && plan.slots.length === 0)) {
+            return { plan, capabilities: known };
+        }
+        const discovered = await new ConventionCapabilityDeltaResolver(this.#modules, this.#model, current).resolve(plan.fallbacks, plan.slots);
+        const subtrees = collapseInvalidationSubtrees([
+            ...plan.subtrees,
+            ...discovered.unresolved.flatMap((fallback) => fallback.owners),
+        ]);
+        const capabilities = filterCapabilityDelta(mergeCapabilityDeltas(known, discovered.capabilities), (owner) => !subtrees.some((root) => isWithinInvalidationRoot(owner, root)));
+        const effective = Object.freeze({
+            ...plan,
+            slots: capabilityDeltaIds(capabilities),
+            subtrees,
+            fallbacks: Object.freeze([]),
+        });
+        return { plan: effective, capabilities };
+    }
     #canPrepareSubtrees(plan) {
         if (plan.subtrees.length === 0 || plan.subtrees.includes(rootPluginId()))
             return false;
@@ -299,6 +312,13 @@ export class RootRuntime {
         }
     }
 }
+function collapseInvalidationSubtrees(values) {
+    const sorted = [...new Set(values)].sort((left, right) => left.length - right.length);
+    return Object.freeze(sorted.filter((candidate, index) => !sorted.slice(0, index).some((root) => isWithinInvalidationRoot(candidate, root))));
+}
+function isWithinInvalidationRoot(plugin, root) {
+    return plugin === root || plugin.startsWith(`${root}/`);
+}
 function withConfigDocumentHandoff(generation, document, committed) {
     const handoffs = new GenerationHandoffStack();
     if (generation.handoff)

package/lib/slot-generation-preparer.d.ts

@@ -1,9 +1,10 @@
 import { type CapabilityId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { ModuleRuntime } from './module-runtime.js';
 import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+import { type CapabilityDelta } from './convention-capability-delta.js';
 export declare class SlotGenerationPreparer {
     private readonly modules;
     private readonly model;
     constructor(modules: ModuleRuntime, model: RuntimeGenerationModel);
-    prepare(current: RuntimeSnapshot, selected: readonly CapabilityId[]): Promise<PreparedRuntimeGeneration>;
+    prepare(current: RuntimeSnapshot, selected: readonly CapabilityId[] | CapabilityDelta): Promise<PreparedRuntimeGeneration>;
 }

package/lib/slot-generation-preparer.js

@@ -3,6 +3,7 @@ import { FeatureDiscovery } from '@zhin.js/feature-kit';
 import { FeatureProjector, composeGenerationHandoffs } from './feature-projector.js';
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { capabilityDeltaFromSlots, } from './convention-capability-delta.js';
 export class SlotGenerationPreparer {
     modules;
     model;
@@ -11,7 +12,9 @@ export class SlotGenerationPreparer {
         this.model = model;
     }
     async prepare(current, selected) {
-        const selectedByFeature = groupByFeature(current, selected);
+        const selectedByFeature = Array.isArray(selected)
+            ? capabilityDeltaFromSlots(current, selected)
+            : selected;
         const capabilities = new Map(current.capabilities);
         const discovery = new FeatureDiscovery(new NodeDiscoveryHost(this.modules));
         for (const [feature, ids] of selectedByFeature) {
@@ -59,18 +62,6 @@ export class SlotGenerationPreparer {
         }
     }
 }
-function groupByFeature(current, selected) {
-    const result = new Map();
-    for (const id of selected) {
-        const slot = current.capabilities.get(id);
-        if (!slot)
-            throw new Error(`Cannot reload missing Capability Slot: ${id}`);
-        const ids = result.get(slot.feature) ?? new Set();
-        ids.add(id);
-        result.set(slot.feature, ids);
-    }
-    return result;
-}
 async function disposeProjections(disposers, prepareError) {
     const rollback = new DisposeStack();
     for (const dispose of disposers)

package/lib/source-ownership.d.ts

@@ -1,4 +1,5 @@
 import type { CapabilityId, FeatureId, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { ModuleWatchRoot } from './module-runtime.js';
 import type { ProjectGraph } from './project-graph.js';
 export type SourceRole = 'plugin' | 'schema' | 'manifest' | 'feature' | 'capability';
 export interface SourceOwnershipRecord {
@@ -16,4 +17,6 @@ export declare class SourceOwnershipIndex {
     addPackageRoot(packageRoot: string, owner: PluginId): void;
     recordsFor(source: string): readonly SourceOwnershipRecord[];
     ownersForPath(source: string): readonly PluginId[];
+    watchRoots(): readonly ModuleWatchRoot[];
+    addWatchRoot(root: ModuleWatchRoot): void;
 }

package/lib/source-ownership.js

@@ -2,11 +2,17 @@ import { isAbsolute, relative, resolve } from 'node:path';
 export class SourceOwnershipIndex {
     #records = new Map();
     #packages = [];
+    #watchRoots = new Map();
     static empty() {
         return new SourceOwnershipIndex();
     }
     static fromGeneration(graph, snapshot, featureIdsByPackageRoot) {
         const index = new SourceOwnershipIndex();
+        for (const pkg of graph.packages.values()) {
+            if (pkg.source === 'node_modules')
+                continue;
+            index.addWatchRoot({ root: pkg.root, source: pkg.source });
+        }
         visitPlugin(graph.root, (node) => {
             index.addPackageRoot(node.package.root, node.id);
             index.add({
@@ -86,6 +92,13 @@ export class SourceOwnershipIndex {
         }
         return Object.freeze([...owners]);
     }
+    watchRoots() {
+        return Object.freeze([...this.#watchRoots.values()]);
+    }
+    addWatchRoot(root) {
+        const normalized = resolve(root.root);
+        this.#watchRoots.set(normalized, Object.freeze({ ...root, root: normalized }));
+    }
 }
 function visitPlugin(node, visit) {
     visit(node);

package/lib/topology-generation-preparer.d.ts

@@ -1,4 +1,4 @@
-import { type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CapabilityId, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { RuntimeEnvironment } from './environment.js';
 import type { EnvironmentLayers } from './environment-store.js';
 import type { RuntimeConfigDocument } from './config-composer.js';
@@ -7,6 +7,13 @@ import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
 import type { ProjectGraph } from './project-graph.js';
 import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+import { type CapabilityDelta } from './convention-capability-delta.js';
+/** Runtime-local invalidation to commit alongside an ABI-safe manifest change. */
+export interface TopologyRuntimeDelta {
+    readonly slots: readonly CapabilityId[];
+    readonly subtrees: readonly PluginId[];
+    readonly capabilities?: CapabilityDelta;
+}
 /** Prepares manifest topology changes without rebuilding stable Plugin Scopes. */
 export declare class TopologyGenerationPreparer {
     #private;
@@ -20,5 +27,5 @@ export declare class TopologyGenerationPreparer {
     private readonly environmentLayers;
     private readonly isolation?;
     constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, graph: ProjectGraph, configResolver: PluginConfigResolver, primaryConfigDocument: RuntimeConfigDocument, environment: RuntimeEnvironment, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, isolation?: IsolatedPluginRuntimePort | undefined);
-    prepare(current: RuntimeSnapshot): Promise<PreparedRuntimeGeneration | undefined>;
+    prepare(current: RuntimeSnapshot, delta?: TopologyRuntimeDelta): Promise<PreparedRuntimeGeneration | undefined>;
 }

package/lib/topology-generation-preparer.js

@@ -6,6 +6,7 @@ import { FeatureProjector, composeGenerationHandoffs } from './feature-projector
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { capabilityDeltaFromSlots, capabilityDeltaIds, } from './convention-capability-delta.js';
 import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 import { TopologyTransactionPlanner, collapseRoots, graphNodes, graphOrder, isWithin, } from './topology-transaction.js';
 /** Prepares manifest topology changes without rebuilding stable Plugin Scopes. */
@@ -30,7 +31,7 @@ export class TopologyGenerationPreparer {
         this.environmentLayers = environmentLayers;
         this.isolation = isolation;
     }
-    async prepare(current) {
+    async prepare(current, delta = { slots: [], subtrees: [] }) {
         const planned = new TopologyTransactionPlanner().plan(this.model.graph, this.graph);
         const nextNodes = graphNodes(this.graph);
         const configReplacements = changedConfigRoots(current, nextNodes, this.configResolver);
@@ -39,7 +40,9 @@ export class TopologyGenerationPreparer {
             ...configReplacements,
         ]);
         const plan = withReplacements(planned, replacedPluginRoots);
-        if (!plan.changed)
+        const subtreeRoots = collapseRoots(delta.subtrees);
+        const selected = delta.capabilities ?? capabilityDeltaFromSlots(current, delta.slots);
+        if (!plan.changed && subtreeRoots.length === 0 && selected.size === 0)
             return undefined;
         const featureTopology = await this.#loadFeatureTopology(plan);
         const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, this.installResources, this.environmentLayers, {
@@ -52,10 +55,12 @@ export class TopologyGenerationPreparer {
         const setupRoots = collapseRoots([
             ...plan.addedPluginRoots,
             ...plan.replacedPluginRoots,
+            ...subtreeRoots,
         ]);
         const removalRoots = collapseRoots([
             ...plan.removedPluginRoots,
             ...plan.replacedPluginRoots,
+            ...subtreeRoots,
         ]);
         plugins.removeSubtrees(removalRoots);
         const projectionDisposers = new Map();
@@ -69,7 +74,7 @@ export class TopologyGenerationPreparer {
             // Retained parents still need a new immutable children view after add,
             // remove, move, or reorder operations.
             plugins.synchronizeTree(this.graph.root);
-            const capabilities = await this.#prepareCapabilities(current, plan, setupRoots, featureTopology);
+            const capabilities = await this.#prepareCapabilities(current, plan, setupRoots, featureTopology, selected);
             mergeSetupCapabilities(capabilities, plugins.setupCapabilities(), featureTopology.providers, featureTopology.rootsByFeature);
             const projected = await new FeatureProjector(featureTopology.providers.values()).project(current.generation + 1, {
                 root: current.root,
@@ -140,7 +145,7 @@ export class TopologyGenerationPreparer {
             featureIdsByPackageRoot: new Map(featureIdsByPackageRoot),
         };
     }
-    async #prepareCapabilities(current, plan, setupRoots, topology) {
+    async #prepareCapabilities(current, plan, setupRoots, topology, selected) {
         const nextOwners = new Set(graphNodes(this.graph).keys());
         const mounted = mountedFeatures(topology);
         const refresh = new Set();
@@ -167,9 +172,13 @@ export class TopologyGenerationPreparer {
                 refresh.add(ownerFeatureKey(mount.owner, previousFeature));
         }
         const capabilities = new Map(current.capabilities);
+        const selectedIds = new Set(capabilityDeltaIds(selected));
         for (const [id, slot] of capabilities) {
             const key = ownerFeatureKey(slot.owner, slot.feature);
-            if (!nextOwners.has(slot.owner) || !mounted.has(key) || refresh.has(key)) {
+            if (!nextOwners.has(slot.owner)
+                || !mounted.has(key)
+                || refresh.has(key)
+                || selectedIds.has(id)) {
                 capabilities.delete(id);
             }
         }
@@ -185,6 +194,19 @@ export class TopologyGenerationPreparer {
                 addCapabilitySlot(capabilities, slot);
             }
         }
+        // A manifest batch can carry a direct capability change. Rediscover the
+        // requested Slots after topology refresh so both observations commit as
+        // one immutable generation instead of racing two reload transactions.
+        const selectedByFeature = selectedSlotsByFeature(current, selected, refresh);
+        for (const [feature, ids] of selectedByFeature) {
+            const provider = topology.providers.get(feature);
+            if (!provider)
+                continue;
+            const roots = topology.rootsByFeature.get(feature) ?? [];
+            for (const slot of await discovery.discover(provider, roots, { capabilities: ids })) {
+                addCapabilitySlot(capabilities, slot);
+            }
+        }
         return capabilities;
     }
 }
@@ -238,6 +260,20 @@ function featureMountsForReload(graph, packageRoots) {
 function ownerFeatureKey(owner, feature) {
     return `${owner}\0${feature}`;
 }
+function selectedSlotsByFeature(current, selected, refreshed) {
+    const result = new Map();
+    for (const [feature, selectedIds] of selected) {
+        for (const id of selectedIds) {
+            const slot = current.capabilities.get(id);
+            if (slot && refreshed.has(ownerFeatureKey(slot.owner, slot.feature)))
+                continue;
+            const ids = result.get(feature) ?? new Set();
+            ids.add(id);
+            result.set(feature, ids);
+        }
+    }
+    return result;
+}
 function sameValues(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,22 +18,22 @@
   "dependencies": {
     "ajv": "8.18.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.0.4",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/feature-kit": "1.0.5",
+    "@zhin.js/plugin-runtime": "1.1.2"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent-feature": "1.0.4",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/component": "1.0.4",
-    "@zhin.js/layout": "1.0.4",
-    "@zhin.js/mcp-feature": "1.0.4",
-    "@zhin.js/middleware": "1.0.4",
-    "@zhin.js/page": "1.0.4",
-    "@zhin.js/skill": "1.0.4",
-    "@zhin.js/tool": "1.0.4"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/command": "1.0.6",
+    "@zhin.js/agent-feature": "1.0.5",
+    "@zhin.js/layout": "1.0.5",
+    "@zhin.js/component": "1.0.5",
+    "@zhin.js/mcp-feature": "1.0.5",
+    "@zhin.js/page": "1.0.5",
+    "@zhin.js/middleware": "1.0.5",
+    "@zhin.js/skill": "1.0.5",
+    "@zhin.js/tool": "1.0.5"
   },
   "repository": {
     "type": "git",