@zhin.js/plugin-runtime 1.1.23 → 1.2.0

package/README.md

@@ -43,4 +43,4 @@ prepare shadow state -> validate -> handoff -> atomic commit
 
 验证：`pnpm --filter @zhin.js/plugin-runtime test && pnpm --filter @zhin.js/plugin-runtime build`。
 
-详细契约见 [Kernel 与 Generation](../../../docs/architecture/target-implementation/kernel-and-generation.md)。
+详细契约见 [Generation 生命周期](../../../docs/concepts/generation-lifecycle.md)。

package/lib/component-host.d.ts

@@ -1,9 +1,11 @@
 /**
  * Outbound template context — conversation + incoming message metadata
- * available as top-level variables inside `${expr}` template expressions.
+ * addressable by `${path}` placeholders in outbound text.
  *
- * Templates can reference e.g. `${sender.name}`, `${adapter}`,
- * `${content}`, `${messageId}`, `${timestamp}`.
+ * A placeholder is a plain property path over these fields, e.g.
+ * `${sender.name}`, `${adapter}`, `${content}`, `${segments[0].type}`.
+ * Nothing is evaluated: arithmetic, calls, unknown names and undefined
+ * values stay in the text exactly as written.
  */
 export interface TemplateContext {
     /** Adapter feature name (e.g. 'qq', 'sandbox'). */
@@ -37,8 +39,9 @@ export interface TemplateContext {
     readonly mentioned?: boolean;
 }
 /**
- * Thin Host Resource for Plugin Runtime outbound template compilation.
- * Evaluates `${expr}` template expressions in a sandboxed VM context
+ * Thin Host Resource for Plugin Runtime outbound template substitution.
+ * Replaces `${path}` placeholders by whitelist path lookup over the
+ * `TemplateContext`; it never evaluates expressions.
  * The Host keeps render authority inside the active Runtime operation.
  *
  * Implemented by the CLI Host; absent when not wired — consumers must

package/lib/inbox.d.ts

@@ -2,10 +2,9 @@ import type { DatabaseHost } from './database-host.js';
 /**
  * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
  *
- * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
- * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
- * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
- * 供 console-rpc-extended 的 request.consumed / notice.consumed 写路径使用。
+ * 本文件是这三张表列结构的 SSOT。request/notice 带 consumed/consumed_at 列，
+ * 供 packages/host/http/src/console-rpc-extended/inbox-rpc.ts 的
+ * request.consumed / notice.consumed 写路径使用。
  */
 export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
 export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";

package/lib/inbox.js

@@ -2,10 +2,9 @@ import { createToken } from './token.js';
 /**
  * 统一收件箱（console endpoint-detail 消息历史/请求/通知视图）表定义与写入辅助。
  *
- * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
- * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
- * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
- * 供 console-rpc-extended 的 request.consumed / notice.consumed 写路径使用。
+ * 本文件是这三张表列结构的 SSOT。request/notice 带 consumed/consumed_at 列，
+ * 供 packages/host/http/src/console-rpc-extended/inbox-rpc.ts 的
+ * request.consumed / notice.consumed 写路径使用。
  */
 export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
 export const INBOX_TABLE_REQUEST = 'unified_inbox_request';

package/lib/index.d.ts

@@ -51,3 +51,5 @@ export * from './relational-target-migration.js';
 export * from './environment-expansion.js';
 export * from './host-installer.js';
 export * from './host-credential-storage.js';
+/** @public ADR 0050 layered feature configuration: resolution keys, resolver and dispatch gate. */
+export * from './layered-config.js';

package/lib/index.js

@@ -51,3 +51,5 @@ export * from './relational-target-migration.js';
 export * from './environment-expansion.js';
 export * from './host-installer.js';
 export * from './host-credential-storage.js';
+/** @public ADR 0050 layered feature configuration: resolution keys, resolver and dispatch gate. */
+export * from './layered-config.js';

package/lib/layered-config.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Layered feature configuration (ADR 0050 / 0055): global < adapter < endpoint < conversation.
+ *
+ * Pure resolution shared by the Runtime (`configFor` / `isEnabledFor`), IM dispatch
+ * gating and Agent tool disclosure. Schema-level checks live in `@zhin.js/runtime`.
+ */
+import { type PrimaryConfig } from './host-installer.js';
+import { type PluginId } from './identity.js';
+import type { RuntimeConfigDocument } from './root-config-document.js';
+import type { RuntimeSnapshot } from './snapshot.js';
+export type FeatureConfigLevel = 'global' | 'adapter' | 'endpoint' | 'conversation';
+export declare const FEATURE_CONFIG_LEVELS: readonly FeatureConfigLevel[];
+/** Levels stored in the configuration file (`conversation` lives in the project database). */
+export type FeatureFileLevel = Exclude<FeatureConfigLevel, 'conversation'>;
+/** Mirrors `ConversationKind` of `@zhin.js/im-contract` (this package has no dependencies). */
+export type FeatureConversationKind = 'group' | 'private' | 'channel';
+export declare const FEATURE_CONVERSATION_KINDS: readonly FeatureConversationKind[];
+/** Longest accepted platform conversation id (unescaped). */
+export declare const FEATURE_CONVERSATION_ID_MAX_LENGTH = 256;
+/** Reserved key in a Plugin's own config block that holds adapter / endpoint overrides. */
+export declare const FEATURE_OVERRIDES_KEY = "overrides";
+/** Reserved field inside one override entry: the level's enable switch. */
+export declare const FEATURE_ENABLED_KEY = "enabled";
+/** Adapter instance alias, the top-level key of an adapter Plugin block. */
+export declare const FEATURE_ADAPTER_KEY_PATTERN: RegExp;
+/** `<alias>/<endpointId>`; endpoint ids exclude the record (`~`) and capability (`\0`) delimiters. */
+export declare const FEATURE_ENDPOINT_KEY_PATTERN: RegExp;
+export type FeatureOverrideEntry = Readonly<Record<string, unknown>> & {
+    readonly enabled?: boolean;
+};
+export interface FeatureOverrides {
+    readonly adapters?: Readonly<Record<string, FeatureOverrideEntry>>;
+    readonly endpoints?: Readonly<Record<string, FeatureOverrideEntry>>;
+}
+/** Parsed resolution key: `''` (global), `'qq'` (adapter), `'qq/bot-1'` (endpoint) or `'qq/bot-1/group:123'` (conversation). */
+export interface FeatureResolutionKey {
+    readonly adapter?: string;
+    readonly endpointId?: string;
+    /** Requires `adapter` and `endpointId`. `id` is the unescaped platform conversation id. */
+    readonly conversation?: FeatureConversationTarget;
+}
+export interface FeatureConversationTarget {
+    readonly kind: FeatureConversationKind;
+    readonly id: string;
+}
+/** One stored conversation-level override (ADR 0055 §3). */
+export interface FeatureConversationOverride {
+    /** Only `false` is ever stored: enabling at a lower level removes the switch. */
+    readonly enabled?: false;
+    /** Field patch limited to the Plugin's `conversationFields`. */
+    readonly patch: Readonly<Record<string, unknown>>;
+    readonly revision: number;
+    readonly updatedAt: number;
+    readonly updatedBy?: string;
+}
+/** Read side of the instance's conversation override store, provided on the Root Scope. */
+export interface FeatureConversationOverrideReader {
+    /** Bumped on every write; resolution caches compare it. */
+    readonly version: number;
+    /** `plugin` is the instance path (`rss`, `parent/child`); `key` a conversation resolution key. */
+    get(plugin: string, key: string): FeatureConversationOverride | undefined;
+}
+export declare const featureConversationOverridesToken: import("./token.js").Token<FeatureConversationOverrideReader>;
+/**
+ * What `configFor` / `isEnabledFor` accept: a resolution key string, an explicit
+ * `{ adapter: <instance alias>, endpointId? }`, or a message-like value carrying
+ * `conversation.endpoint.id` (resolved through the generation's AdapterIndex).
+ */
+export type FeatureTarget = string | Readonly<{
+    adapter: string;
+    endpointId?: string;
+    conversation?: FeatureConversationTarget;
+}> | Readonly<{
+    conversation: Readonly<{
+        endpoint: Readonly<{
+            id: string;
+        }>;
+        kind?: string;
+        id?: string;
+    }>;
+    endpointId?: string;
+}>
+/**
+ * An outbound selector (`outbound.send({ adapter, endpointKey })`): resolved to the Endpoint's
+ * CapabilityId through the same `AdapterIndex.resolve` path as the send, so platform names,
+ * online names and omitted keys address the same account the send reaches.
+ */
+ | Readonly<{
+    endpoint: Readonly<{
+        adapter: string;
+        endpointKey: string;
+    }>;
+    conversation?: Readonly<{
+        kind?: string;
+        id?: string;
+    }>;
+}>;
+export interface FeatureEnabledResolution {
+    readonly enabled: boolean;
+    /** Highest level whose switch is off. */
+    readonly disabledAt?: FeatureConfigLevel;
+    /**
+     * Set when a level above the queried one disabled the feature. The queried level is then
+     * locked: it can neither enable nor change its own switch (ADR 0050 §4).
+     */
+    readonly lockedBy?: FeatureFileLevel;
+}
+export interface LayeredConfigResolution<T = Readonly<Record<string, unknown>>> extends FeatureEnabledResolution {
+    /** Normalized resolution key (`''`, `alias`, `alias/endpointId` or `alias/endpointId/kind:id`). */
+    readonly key: string;
+    /** Effective value: deep-merged and frozen. Fields cleared with `null` are absent. */
+    readonly value: Readonly<T>;
+    /** JSON Pointer of every effective leaf (and every cleared path) → the level that set it. */
+    readonly sources: Readonly<Record<string, FeatureConfigLevel>>;
+}
+export interface LayeredConfigInput {
+    readonly global: unknown;
+    readonly overrides?: unknown;
+    /** False when the instance alias is listed in `disable_plugins`. */
+    readonly globalEnabled?: boolean;
+    readonly key?: FeatureResolutionKey | string;
+    /** Conversation-level entry (`{ enabled?: false, ...patch }`); used only for conversation keys. */
+    readonly conversation?: FeatureOverrideEntry;
+}
+/**
+ * Escapes a platform conversation id for a resolution key: `%` → `%25`, `/` → `%2F`, nothing
+ * else. The key then has exactly two `/` separators and the id round-trips unchanged.
+ */
+export declare function escapeFeatureConversationId(id: string): string;
+/** Inverse of {@link escapeFeatureConversationId}; undefined for any other `%` sequence or a raw `/`. */
+export declare function unescapeFeatureConversationId(escaped: string): string | undefined;
+/** Whether `id` can be a conversation key id: 1–256 characters without control characters. */
+export declare function isFeatureConversationId(id: unknown): id is string;
+/** `<alias>/<endpointId>/<kind>:<escaped id>` (ADR 0055 §1). */
+export declare function formatFeatureConversationKey(adapter: string, endpointId: string, conversation: FeatureConversationTarget): string;
+/** Parses a conversation key; undefined for adapter / endpoint keys and malformed input. */
+export declare function parseFeatureConversationKey(key: string): Required<FeatureResolutionKey> | undefined;
+export declare function parseFeatureResolutionKey(key: string | FeatureResolutionKey | undefined): FeatureResolutionKey;
+export declare function formatFeatureResolutionKey(key: FeatureResolutionKey | string | undefined): string;
+/** The endpoint key above a conversation key (`qq/bot/group:1` → `qq/bot`); other keys unchanged. */
+export declare function featureEndpointKeyOf(key: string): string;
+/** Conversation entry as resolution input: `{ enabled?: false, ...patch }`. */
+export declare function featureConversationEntry(override: FeatureConversationOverride | undefined): FeatureOverrideEntry | undefined;
+/** The Root Scope's conversation override reader, when the instance provides one. */
+export declare function readFeatureConversationOverrides(snapshot: Pick<RuntimeSnapshot, 'root' | 'resources'> | undefined): FeatureConversationOverrideReader | undefined;
+/** Instance path (`rss`, `parent/child`) of a non-root Plugin id. */
+export declare function featureInstancePath(owner: PluginId): string;
+/** Reads the structural `overrides` value; anything malformed contributes nothing. */
+export declare function readFeatureOverrides(value: unknown): FeatureOverrides;
+/** Level a resolution key addresses. */
+export declare function featureKeyLevel(key: FeatureResolutionKey | string | undefined): FeatureConfigLevel;
+/**
+ * Top-down: an upper `false` wins and a lower `enabled: true` never re-enables. A level is
+ * locked (`lockedBy`) when any level above it is off; it may only disable while every upper
+ * level is on (ADR 0050 §4, ADR 0055 §4).
+ */
+export declare function resolveFeatureEnabled(input: Omit<LayeredConfigInput, 'global'> & {
+    readonly level?: FeatureConfigLevel;
+}): FeatureEnabledResolution;
+export declare function escapeJsonPointerSegment(segment: string): string;
+/** Bottom-up merge `global ← adapter ← endpoint ← conversation` with per-field source tracking. */
+export declare function resolveLayeredConfig<T = Readonly<Record<string, unknown>>>(input: LayeredConfigInput): LayeredConfigResolution<T>;
+/** Source of one field path, falling back to the nearest recorded ancestor (a whole replaced object). */
+export declare function featureConfigSource(resolution: Pick<LayeredConfigResolution, 'sources'>, path: readonly string[]): FeatureConfigLevel | undefined;
+/** The document address of one Plugin instance's own config block (`root/a/b` → `['a', 'b']`). */
+export declare function pluginConfigBlockPath(owner: PluginId): readonly string[];
+export declare function readPluginConfigBlock(document: RuntimeConfigDocument | undefined, owner: PluginId): Readonly<Record<string, unknown>> | undefined;
+export declare function readPrimaryConfig(snapshot: Pick<RuntimeSnapshot, 'root' | 'resources'>): PrimaryConfig | undefined;
+/**
+ * Maps a message endpoint (`conversation.endpoint.id`, a CapabilityId) to its resolution key
+ * `<adapter instance alias>/<endpointId>`; undefined when this generation does not know it.
+ * With `conversation` (kind + platform id) the key goes down to the conversation level; an id
+ * that cannot be keyed (too long, control characters) stays at the endpoint level.
+ */
+export declare function resolveEndpointFeatureKey(snapshot: Pick<RuntimeSnapshot, 'projections' | 'tree'>, endpointCapabilityId: string, fallbackEndpointId?: string, conversation?: Readonly<{
+    kind?: unknown;
+    id?: unknown;
+}>): string | undefined;
+/** Normalizes any {@link FeatureTarget}; message targets need the generation's AdapterIndex. */
+export declare function resolveFeatureTargetKey(snapshot: Pick<RuntimeSnapshot, 'projections' | 'tree'> | undefined, target: FeatureTarget): string | undefined;
+/**
+ * Dispatch gate: whether `owner` is enabled for one resolution key in this generation.
+ * Plugins listed in `disable_plugins` never load, so only override levels are consulted here.
+ * Conversation keys also read the instance's conversation overrides; the cache is keyed by
+ * (configuration generation, store version, owner, key).
+ */
+export declare function isFeatureOwnerEnabled(snapshot: Pick<RuntimeSnapshot, 'root' | 'resources'>, owner: PluginId, key: string | undefined): boolean;
+/** Owners in `owners` that are switched off for `key`; empty for global keys. */
+export declare function disabledFeatureOwners(snapshot: Pick<RuntimeSnapshot, 'root' | 'resources'>, owners: Iterable<PluginId>, key: string | undefined): ReadonlySet<PluginId>;

package/lib/layered-config.js

@@ -0,0 +1,437 @@
+/**
+ * Layered feature configuration (ADR 0050 / 0055): global < adapter < endpoint < conversation.
+ *
+ * Pure resolution shared by the Runtime (`configFor` / `isEnabledFor`), IM dispatch
+ * gating and Agent tool disclosure. Schema-level checks live in `@zhin.js/runtime`.
+ */
+import { primaryConfigToken } from './host-installer.js';
+import { featureId } from './identity.js';
+import { createToken } from './token.js';
+export const FEATURE_CONFIG_LEVELS = Object.freeze(['global', 'adapter', 'endpoint', 'conversation']);
+export const FEATURE_CONVERSATION_KINDS = Object.freeze(['group', 'private', 'channel']);
+/** Longest accepted platform conversation id (unescaped). */
+export const FEATURE_CONVERSATION_ID_MAX_LENGTH = 256;
+/** Reserved key in a Plugin's own config block that holds adapter / endpoint overrides. */
+export const FEATURE_OVERRIDES_KEY = 'overrides';
+/** Reserved field inside one override entry: the level's enable switch. */
+export const FEATURE_ENABLED_KEY = 'enabled';
+/** Adapter instance alias, the top-level key of an adapter Plugin block. */
+export const FEATURE_ADAPTER_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+/** `<alias>/<endpointId>`; endpoint ids exclude the record (`~`) and capability (`\0`) delimiters. */
+export const FEATURE_ENDPOINT_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*\/[^/~\0]+$/u;
+export const featureConversationOverridesToken = createToken('zhin.feature-conversation-overrides', 'Conversation-level feature overrides (ADR 0055), read side');
+function plainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+const ADAPTER_ALIAS = /^[a-z0-9][a-z0-9-]*$/u;
+const ENDPOINT_ID = /^[^/~\0]{1,128}$/u;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+/**
+ * Escapes a platform conversation id for a resolution key: `%` → `%25`, `/` → `%2F`, nothing
+ * else. The key then has exactly two `/` separators and the id round-trips unchanged.
+ */
+export function escapeFeatureConversationId(id) {
+    return id.replaceAll('%', '%25').replaceAll('/', '%2F');
+}
+/** Inverse of {@link escapeFeatureConversationId}; undefined for any other `%` sequence or a raw `/`. */
+export function unescapeFeatureConversationId(escaped) {
+    if (/%(?!25|2[fF])/u.test(escaped) || escaped.includes('/'))
+        return undefined;
+    return escaped.replace(/%2[fF]|%25/gu, match => match === '%25' ? '%' : '/');
+}
+/** Whether `id` can be a conversation key id: 1–256 characters without control characters. */
+export function isFeatureConversationId(id) {
+    return typeof id === 'string' && id.length > 0 && id.length <= FEATURE_CONVERSATION_ID_MAX_LENGTH && !CONTROL_CHARACTERS.test(id);
+}
+function assertConversationParts(adapter, endpointId, conversation) {
+    if (!ADAPTER_ALIAS.test(adapter))
+        throw new TypeError('A conversation resolution key requires an adapter instance alias');
+    if (!ENDPOINT_ID.test(endpointId))
+        throw new TypeError('A conversation resolution key requires a valid endpointId');
+    if (!FEATURE_CONVERSATION_KINDS.includes(conversation.kind))
+        throw new TypeError('Conversation kind must be group, private or channel');
+    if (!isFeatureConversationId(conversation.id))
+        throw new TypeError('Conversation id must be 1-256 characters without control characters');
+}
+/** `<alias>/<endpointId>/<kind>:<escaped id>` (ADR 0055 §1). */
+export function formatFeatureConversationKey(adapter, endpointId, conversation) {
+    assertConversationParts(adapter, endpointId, conversation);
+    return `${adapter}/${endpointId}/${conversation.kind}:${escapeFeatureConversationId(conversation.id)}`;
+}
+/** Parses a conversation key; undefined for adapter / endpoint keys and malformed input. */
+export function parseFeatureConversationKey(key) {
+    const first = key.indexOf('/');
+    const second = first < 0 ? -1 : key.indexOf('/', first + 1);
+    if (first <= 0 || second < 0)
+        return undefined;
+    const rest = key.slice(second + 1);
+    const colon = rest.indexOf(':');
+    if (colon <= 0)
+        return undefined;
+    const id = unescapeFeatureConversationId(rest.slice(colon + 1));
+    if (id === undefined)
+        return undefined;
+    const parsed = { adapter: key.slice(0, first), endpointId: key.slice(first + 1, second),
+        conversation: Object.freeze({ kind: rest.slice(0, colon), id }) };
+    try {
+        assertConversationParts(parsed.adapter, parsed.endpointId, parsed.conversation);
+    }
+    catch {
+        return undefined;
+    }
+    return formatFeatureConversationKey(parsed.adapter, parsed.endpointId, parsed.conversation) === key ? Object.freeze(parsed) : undefined;
+}
+export function parseFeatureResolutionKey(key) {
+    if (key === undefined || key === '')
+        return Object.freeze({});
+    if (typeof key !== 'string') {
+        if (key.endpointId !== undefined && key.adapter === undefined)
+            throw new TypeError('An endpoint resolution key requires its adapter alias');
+        if (key.conversation !== undefined) {
+            if (key.adapter === undefined || key.endpointId === undefined)
+                throw new TypeError('A conversation resolution key requires its adapter alias and endpointId');
+            assertConversationParts(key.adapter, key.endpointId, key.conversation);
+        }
+        return Object.freeze({ ...(key.adapter !== undefined ? { adapter: key.adapter } : {}), ...(key.endpointId !== undefined ? { endpointId: key.endpointId } : {}),
+            ...(key.conversation !== undefined ? { conversation: Object.freeze({ kind: key.conversation.kind, id: key.conversation.id }) } : {}) });
+    }
+    const slash = key.indexOf('/');
+    if (slash < 0)
+        return Object.freeze({ adapter: key });
+    if (key.indexOf('/', slash + 1) >= 0) {
+        const conversation = parseFeatureConversationKey(key);
+        if (!conversation)
+            throw new TypeError('Invalid conversation resolution key (expected <alias>/<endpointId>/<kind>:<escaped id>)');
+        return conversation;
+    }
+    return Object.freeze({ adapter: key.slice(0, slash), endpointId: key.slice(slash + 1) });
+}
+export function formatFeatureResolutionKey(key) {
+    const parsed = parseFeatureResolutionKey(key);
+    if (parsed.adapter === undefined)
+        return '';
+    if (parsed.endpointId === undefined)
+        return parsed.adapter;
+    return parsed.conversation === undefined ? `${parsed.adapter}/${parsed.endpointId}`
+        : formatFeatureConversationKey(parsed.adapter, parsed.endpointId, parsed.conversation);
+}
+/** The endpoint key above a conversation key (`qq/bot/group:1` → `qq/bot`); other keys unchanged. */
+export function featureEndpointKeyOf(key) {
+    const parsed = parseFeatureResolutionKey(key);
+    return parsed.conversation ? `${parsed.adapter}/${parsed.endpointId}` : formatFeatureResolutionKey(parsed);
+}
+/** Conversation entry as resolution input: `{ enabled?: false, ...patch }`. */
+export function featureConversationEntry(override) {
+    if (!override)
+        return undefined;
+    return Object.freeze({ ...override.patch, ...(override.enabled === false ? { [FEATURE_ENABLED_KEY]: false } : {}) });
+}
+/** The Root Scope's conversation override reader, when the instance provides one. */
+export function readFeatureConversationOverrides(snapshot) {
+    const value = snapshot?.resources.get(snapshot.root)?.get(featureConversationOverridesToken.id);
+    return value && typeof value.get === 'function' ? value : undefined;
+}
+/** Instance path (`rss`, `parent/child`) of a non-root Plugin id. */
+export function featureInstancePath(owner) {
+    return String(owner).split('/').slice(1).join('/');
+}
+/** Reads the structural `overrides` value; anything malformed contributes nothing. */
+export function readFeatureOverrides(value) {
+    if (!plainObject(value))
+        return Object.freeze({});
+    const pick = (entries) => {
+        if (!plainObject(entries))
+            return undefined;
+        return Object.freeze(Object.fromEntries(Object.entries(entries)
+            .filter((entry) => plainObject(entry[1]))));
+    };
+    const adapters = pick(value.adapters);
+    const endpoints = pick(value.endpoints);
+    return Object.freeze({ ...(adapters ? { adapters } : {}), ...(endpoints ? { endpoints } : {}) });
+}
+function overrideEntries(overrides, key) {
+    const adapter = key.adapter !== undefined && Object.hasOwn(overrides.adapters ?? {}, key.adapter)
+        ? overrides.adapters[key.adapter] : undefined;
+    const endpointKey = key.adapter !== undefined && key.endpointId !== undefined ? `${key.adapter}/${key.endpointId}` : undefined;
+    const endpoint = endpointKey !== undefined && Object.hasOwn(overrides.endpoints ?? {}, endpointKey)
+        ? overrides.endpoints[endpointKey] : undefined;
+    return { ...(adapter ? { adapter } : {}), ...(endpoint ? { endpoint } : {}) };
+}
+/** Level a resolution key addresses. */
+export function featureKeyLevel(key) {
+    const parsed = parseFeatureResolutionKey(key);
+    return parsed.conversation !== undefined ? 'conversation' : parsed.endpointId !== undefined ? 'endpoint' : parsed.adapter !== undefined ? 'adapter' : 'global';
+}
+/**
+ * Top-down: an upper `false` wins and a lower `enabled: true` never re-enables. A level is
+ * locked (`lockedBy`) when any level above it is off; it may only disable while every upper
+ * level is on (ADR 0050 §4, ADR 0055 §4).
+ */
+export function resolveFeatureEnabled(input) {
+    const key = parseFeatureResolutionKey(input.key);
+    const { adapter, endpoint } = overrideEntries(readFeatureOverrides(input.overrides), key);
+    const conversation = key.conversation !== undefined && plainObject(input.conversation) ? input.conversation : undefined;
+    const disabledAt = input.globalEnabled === false ? 'global'
+        : adapter?.enabled === false ? 'adapter'
+            : endpoint?.enabled === false ? 'endpoint'
+                : conversation?.enabled === false ? 'conversation' : undefined;
+    const level = input.level ?? featureKeyLevel(key);
+    const rank = (value) => FEATURE_CONFIG_LEVELS.indexOf(value);
+    const lockedBy = disabledAt !== undefined && disabledAt !== 'conversation' && rank(disabledAt) < rank(level) ? disabledAt : undefined;
+    return Object.freeze({ enabled: disabledAt === undefined, ...(disabledAt ? { disabledAt } : {}), ...(lockedBy ? { lockedBy } : {}) });
+}
+export function escapeJsonPointerSegment(segment) {
+    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function clearSources(sources, path) {
+    for (const existing of Object.keys(sources)) {
+        if (existing === path || existing.startsWith(`${path}/`))
+            delete sources[existing];
+    }
+}
+function markLeaves(value, path, level, sources) {
+    if (plainObject(value) && Object.keys(value).length > 0) {
+        for (const [key, child] of Object.entries(value))
+            markLeaves(child, `${path}/${escapeJsonPointerSegment(key)}`, level, sources);
+        return;
+    }
+    sources[path] = level;
+}
+function mergeLayer(base, layer, level, prefix, sources, top) {
+    for (const [key, value] of Object.entries(layer)) {
+        if (value === undefined || (top && (key === FEATURE_ENABLED_KEY || key === FEATURE_OVERRIDES_KEY)))
+            continue;
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
+        const path = `${prefix}/${escapeJsonPointerSegment(key)}`;
+        if (value === null) {
+            // Explicit clear: the field stops inheriting and is absent from the effective value.
+            delete base[key];
+            clearSources(sources, path);
+            sources[path] = level;
+            continue;
+        }
+        if (plainObject(value)) {
+            const current = base[key];
+            if (!plainObject(current))
+                clearSources(sources, path);
+            base[key] = mergeLayer(plainObject(current) ? { ...current } : {}, value, level, path, sources, false);
+            if (Object.keys(value).length === 0 && !plainObject(current))
+                sources[path] = level;
+            continue;
+        }
+        // Arrays and scalars replace whole.
+        clearSources(sources, path);
+        base[key] = structuredClone(value);
+        sources[path] = level;
+    }
+    return base;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Bottom-up merge `global ← adapter ← endpoint ← conversation` with per-field source tracking. */
+export function resolveLayeredConfig(input) {
+    const key = parseFeatureResolutionKey(input.key);
+    const overrides = readFeatureOverrides(input.overrides);
+    const sources = {};
+    const global = plainObject(input.global) ? input.global : {};
+    const { [FEATURE_OVERRIDES_KEY]: _ignored, ...globalFields } = global;
+    for (const [field, value] of Object.entries(globalFields)) {
+        if (value !== undefined)
+            markLeaves(value, `/${escapeJsonPointerSegment(field)}`, 'global', sources);
+    }
+    let value = structuredClone(globalFields);
+    const { adapter, endpoint } = overrideEntries(overrides, key);
+    if (adapter)
+        value = mergeLayer(value, adapter, 'adapter', '', sources, true);
+    if (endpoint)
+        value = mergeLayer(value, endpoint, 'endpoint', '', sources, true);
+    const conversation = key.conversation !== undefined && plainObject(input.conversation) ? input.conversation : undefined;
+    if (conversation)
+        value = mergeLayer(value, conversation, 'conversation', '', sources, true);
+    const enabled = resolveFeatureEnabled({ overrides, globalEnabled: input.globalEnabled, key, ...(conversation ? { conversation } : {}) });
+    return deepFreeze({
+        ...enabled,
+        key: formatFeatureResolutionKey(key),
+        value: value,
+        sources: Object.fromEntries(Object.entries(sources).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)),
+    });
+}
+/** Source of one field path, falling back to the nearest recorded ancestor (a whole replaced object). */
+export function featureConfigSource(resolution, path) {
+    for (let length = path.length; length > 0; length -= 1) {
+        const pointer = `/${path.slice(0, length).map(escapeJsonPointerSegment).join('/')}`;
+        const source = resolution.sources[pointer];
+        if (source)
+            return source;
+    }
+    return undefined;
+}
+/** The document address of one Plugin instance's own config block (`root/a/b` → `['a', 'b']`). */
+export function pluginConfigBlockPath(owner) {
+    const parts = String(owner).split('/');
+    return Object.freeze(parts.slice(1));
+}
+export function readPluginConfigBlock(document, owner) {
+    const path = pluginConfigBlockPath(owner);
+    if (!document || path.length === 0)
+        return undefined;
+    let value = document;
+    for (const segment of path) {
+        if (!plainObject(value) || !Object.hasOwn(value, segment))
+            return undefined;
+        value = value[segment];
+    }
+    return plainObject(value) ? value : undefined;
+}
+export function readPrimaryConfig(snapshot) {
+    return snapshot.resources.get(snapshot.root)?.get(primaryConfigToken.id);
+}
+const adapterProjectionId = featureId('zhin.adapter');
+function endpointIndex(snapshot) {
+    const value = snapshot.projections.get(adapterProjectionId);
+    return value && typeof value.owner === 'function' && typeof value.endpointEntry === 'function'
+        ? value : undefined;
+}
+/**
+ * Maps a message endpoint (`conversation.endpoint.id`, a CapabilityId) to its resolution key
+ * `<adapter instance alias>/<endpointId>`; undefined when this generation does not know it.
+ * With `conversation` (kind + platform id) the key goes down to the conversation level; an id
+ * that cannot be keyed (too long, control characters) stays at the endpoint level.
+ */
+export function resolveEndpointFeatureKey(snapshot, endpointCapabilityId, fallbackEndpointId, conversation) {
+    const index = endpointIndex(snapshot);
+    if (!index)
+        return undefined;
+    let owner;
+    try {
+        owner = index.owner(endpointCapabilityId);
+    }
+    catch {
+        return undefined;
+    }
+    const alias = snapshot.tree.get(owner)?.instanceKey;
+    if (!alias)
+        return undefined;
+    let endpointId;
+    try {
+        endpointId = index.endpointEntry(endpointCapabilityId)?.desired?.endpointId;
+    }
+    catch {
+        endpointId = undefined;
+    }
+    const id = typeof endpointId === 'string' && endpointId ? endpointId
+        : typeof fallbackEndpointId === 'string' && fallbackEndpointId ? fallbackEndpointId : undefined;
+    if (id === undefined)
+        return alias;
+    if (conversation && FEATURE_CONVERSATION_KINDS.includes(conversation.kind) && isFeatureConversationId(conversation.id)) {
+        try {
+            return formatFeatureConversationKey(alias, id, { kind: conversation.kind, id: conversation.id });
+        }
+        catch { /* an endpoint id that cannot carry conversations stays at the endpoint level */ }
+    }
+    return `${alias}/${id}`;
+}
+/** Normalizes any {@link FeatureTarget}; message targets need the generation's AdapterIndex. */
+export function resolveFeatureTargetKey(snapshot, target) {
+    if (typeof target === 'string')
+        return formatFeatureResolutionKey(target);
+    if (!target || typeof target !== 'object')
+        throw new TypeError('Feature target must be a resolution key, { adapter, endpointId } or a message');
+    const selector = target.endpoint;
+    if (selector && typeof selector === 'object' && !('id' in selector)) {
+        const { adapter, endpointKey } = selector;
+        if (typeof adapter !== 'string' || typeof endpointKey !== 'string' || !snapshot)
+            return undefined;
+        const index = endpointIndex(snapshot);
+        let id;
+        try {
+            id = index?.resolve?.(adapter, endpointKey);
+        }
+        catch {
+            id = undefined;
+        }
+        if (!id)
+            return undefined;
+        const conversation = target.conversation;
+        return resolveEndpointFeatureKey(snapshot, String(id), undefined, conversation);
+    }
+    const conversation = target.conversation;
+    if (conversation && typeof conversation === 'object' && 'endpoint' in conversation) {
+        const message = target;
+        const id = message.conversation?.endpoint?.id;
+        if (typeof id !== 'string' || !snapshot)
+            return undefined;
+        return resolveEndpointFeatureKey(snapshot, id, typeof message.endpointId === 'string' ? message.endpointId : undefined, message.conversation);
+    }
+    const explicit = target;
+    if (typeof explicit.adapter !== 'string' || !explicit.adapter)
+        throw new TypeError('Feature target adapter must be an instance alias');
+    return formatFeatureResolutionKey({ adapter: explicit.adapter, ...(typeof explicit.endpointId === 'string' ? { endpointId: explicit.endpointId } : {}),
+        ...(explicit.conversation !== undefined ? { conversation: explicit.conversation } : {}) });
+}
+const enabledCache = new WeakMap();
+/** Bound for one generation's per-key cache; conversations are open-ended. */
+const ENABLED_CACHE_LIMIT = 20_000;
+/**
+ * Dispatch gate: whether `owner` is enabled for one resolution key in this generation.
+ * Plugins listed in `disable_plugins` never load, so only override levels are consulted here.
+ * Conversation keys also read the instance's conversation overrides; the cache is keyed by
+ * (configuration generation, store version, owner, key).
+ */
+export function isFeatureOwnerEnabled(snapshot, owner, key) {
+    if (!key || owner === snapshot.root)
+        return true;
+    const primary = readPrimaryConfig(snapshot);
+    if (!primary)
+        return true;
+    let parsed;
+    try {
+        parsed = parseFeatureResolutionKey(key);
+    }
+    catch {
+        return true;
+    }
+    const reader = parsed.conversation ? readFeatureConversationOverrides(snapshot) : undefined;
+    const version = reader?.version ?? -1;
+    let cache = enabledCache.get(primary);
+    if (!cache || (reader && cache.version !== version)) {
+        // A store write invalidates the generation's cache; file-level entries are rebuilt cheaply.
+        cache = { version: reader ? version : cache?.version ?? -1, entries: new Map() };
+        enabledCache.set(primary, cache);
+    }
+    const cacheKey = `${String(owner)}\0${key}`;
+    const cached = cache.entries.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const overrides = readPluginConfigBlock(primary.document, owner)?.[FEATURE_OVERRIDES_KEY];
+    const conversation = reader ? featureConversationEntry(reader.get(featureInstancePath(owner), key)) : undefined;
+    // A nested Plugin inherits its ancestors' switches: a disabled parent hides its children too.
+    const parent = String(owner).slice(0, String(owner).lastIndexOf('/'));
+    const enabled = (parent === snapshot.root || !String(parent) || isFeatureOwnerEnabled(snapshot, parent, key))
+        && resolveFeatureEnabled({ overrides, key, ...(conversation ? { conversation } : {}) }).enabled;
+    if (cache.entries.size >= ENABLED_CACHE_LIMIT)
+        cache.entries.clear();
+    cache.entries.set(cacheKey, enabled);
+    return enabled;
+}
+/** Owners in `owners` that are switched off for `key`; empty for global keys. */
+export function disabledFeatureOwners(snapshot, owners, key) {
+    const disabled = new Set();
+    if (!key)
+        return disabled;
+    for (const owner of owners)
+        if (!isFeatureOwnerEnabled(snapshot, owner, key))
+            disabled.add(owner);
+    return disabled;
+}

package/lib/plugin-console-rpc.d.ts

@@ -60,7 +60,26 @@ export interface PluginConsoleRpcStatus<TConfig = Record<string, unknown>> exten
     /** Allow the demo-scope Console token to read this status. Default `false`. */
     readonly demo?: boolean;
 }
+/**
+ * Level of a plugin-defined permission (ADR 0049 amendment 2026-11-11). Built-in roles grant by
+ * level: viewer → read; operator → read + operate; admin and owner → all.
+ */
+export type PluginConsolePermissionLevel = 'read' | 'operate' | 'manage';
+/** Metadata for a permission string used in this plugin's pages or Console RPC. */
+export interface PluginConsolePermission {
+    /** `<plugin>:<action>`, e.g. `rss:read`, `ops:approve`. */
+    readonly id: string;
+    readonly level: PluginConsolePermissionLevel;
+    /** Short label for the Console's role editor. */
+    readonly description?: string;
+}
 export interface PluginConsoleRpcDefinition<TConfig = Record<string, unknown>> {
+    /**
+     * Levels of the permissions this plugin uses (its pages' and methods' requirements). An
+     * undeclared permission takes its level from the suffix: `:read` / `:view` → read;
+     * `:approve` / `:manage` / `:admin` / `:write` / `:config` → manage; anything else → operate.
+     */
+    readonly permissions?: readonly PluginConsolePermission[];
     /** Read-only status for the plugin's Console page(s): `plugin.<pluginId>.status`. */
     readonly status?: PluginConsoleRpcStatus<TConfig>;
     /**
@@ -92,6 +111,8 @@ export interface NormalizedPluginConsoleRpcMethod {
 /** Value published under {@link pluginConsoleRpcToken}; create it with {@link definePluginConsoleRpc}. */
 export interface PluginConsoleRpc extends GenerationAdmissionSource {
     readonly methods: ReadonlyMap<string, NormalizedPluginConsoleRpcMethod>;
+    /** Declared permission levels; absent or empty when the plugin declared none. */
+    readonly permissions?: readonly PluginConsolePermission[];
 }
 /** Safe, user-facing failure. `message` is shown in the Console; never put raw errors in it. */
 export declare class PluginConsoleRpcError extends Error {

package/lib/plugin-console-rpc.js

@@ -35,10 +35,12 @@ export function definePluginConsoleRpc(definition) {
     }
     if (methods.size === 0)
         throw new TypeError('Plugin Console RPC must declare status or at least one action');
+    const permissions = permissionDeclarations(definition.permissions);
     const gate = createGenerationAdmissionGate();
     const gates = Object.freeze([gate]);
     return Object.freeze({
         methods: methods,
+        ...(permissions.length ? { permissions } : {}),
         get [generationAdmissionSource]() { return gates; },
     });
 }
@@ -66,6 +68,37 @@ function normalizeMethod(name, method, demo, readOnly) {
         handler: method.handler,
     });
 }
+// Same shape as `CONSOLE_PLUGIN_PERMISSION_PATTERN` in @zhin.js/console-protocol (this package has no deps).
+const permissionIdPattern = /^[a-z][a-z0-9_-]{0,63}:[a-z][a-z0-9_.-]{0,63}$/u;
+const permissionLevels = new Set(['read', 'operate', 'manage']);
+function permissionDeclarations(value) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value))
+        throw new TypeError('Plugin Console RPC permissions must be an array');
+    const seen = new Set();
+    return Object.freeze(value.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            throw new TypeError('Plugin Console RPC permission must be an object');
+        const { id, level, description, ...rest } = item;
+        if (Object.keys(rest).length)
+            throw new TypeError(`Plugin Console RPC permission has unknown keys: ${Object.keys(rest).sort().join(', ')}`);
+        if (typeof id !== 'string' || !permissionIdPattern.test(id))
+            throw new TypeError('Plugin Console RPC permission id must look like <plugin>:<action>');
+        if (seen.has(id))
+            throw new TypeError(`Duplicate plugin Console RPC permission: ${id}`);
+        seen.add(id);
+        if (typeof level !== 'string' || !permissionLevels.has(level))
+            throw new TypeError(`Plugin Console RPC permission ${id} level must be read, operate or manage`);
+        if (description !== undefined && (typeof description !== 'string' || !description.trim() || description.length > 256)) {
+            throw new TypeError(`Plugin Console RPC permission ${id} description must be a non-empty string (at most 256 characters)`);
+        }
+        return Object.freeze({
+            id, level: level,
+            ...(description === undefined ? {} : { description: description.trim() }),
+        });
+    }));
+}
 function stringList(value, label) {
     if (value === undefined)
         return Object.freeze([]);

package/lib/plugin.d.ts

@@ -6,6 +6,7 @@ import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
+import type { FeatureTarget } from './layered-config.js';
 import type { PluginEventSubscriptions } from './plugin-events.js';
 import { type PluginConfigUpdateDeclaration } from './config-update-declaration.js';
 import { type PluginConsoleRpc, type PluginConsoleRpcDefinition } from './plugin-console-rpc.js';
@@ -42,6 +43,15 @@ export interface PluginSetupContext<TConfig = unknown> {
     readonly signal: AbortSignal;
     readonly plugin: PluginInstanceView;
     readonly config: ConfigView<TConfig>;
+    /**
+     * Effective configuration for one adapter / endpoint (ADR 0050): `global ← adapter ← endpoint`,
+     * merged, frozen and cached per configuration generation. `target` is a message, an explicit
+     * `{ adapter: <instance alias>, endpointId? }` or a resolution key such as `'qq/bot-1'`.
+     * Reads the latest committed configuration, so in-place override changes are visible without reload.
+     */
+    configFor(target: FeatureTarget): Readonly<TConfig>;
+    /** Effective enable state for one adapter / endpoint; an upper-level disable always wins. */
+    isEnabledFor(target: FeatureTarget): boolean;
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
     readonly handoff: GenerationHandoffRegistry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.23",
+  "version": "1.2.0",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",