@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/extensions/permission-view.d.ts

@@ -0,0 +1,194 @@
+import { type PermissionSet } from "./permission-set.js";
+import type { ExtensionSource } from "./sources.js";
+/**
+ * Review digest: the first 16 hex digits of `sha256(permissionKeys(set).join("\n"))`; with migration
+ * warnings their digest (kind, file, line and statement) is folded in, without warnings it equals the
+ * permissions-only digest. The caller sends it back when approving, and approval is refused when it
+ * differs from the one recomputed now (permissions or warnings changed after the review,
+ * `extension.approval_stale`).
+ */
+export declare function reviewHash(set: PermissionSet, warnings?: readonly PackageWarning[]): string;
+/** 权限清单展示用的一组：按类别分组，`sensitive` 标出需要管理员特别留意的类别。 */
+export interface PermissionGroup {
+    category: "provides" | "requires" | "optional" | "config" | "tables" | "secrets" | "storage" | "http" | "publicRoutes" | "tools" | "hooks" | "models" | "network" | "ui";
+    /**
+     * Sensitive category: secrets, public routes, tools, hooks; also the "provides" group when it holds
+     * one of {@link SENSITIVE_EXTENSION_POINTS}, and the "UI" group when it holds an embedded app
+     * (embed: the extension's own page in an iframe).
+     */
+    sensitive: boolean;
+    items: string[];
+    /** 与 `items` 一一对应：逐项的敏感标记与原因（界面据此高亮并写原因，不自己判定）。 */
+    entries: PermissionItem[];
+}
+/**
+ * Sensitive reason codes (the UI translates them by code): secrets, public routes, tools, hooks,
+ * embedded apps, and sensitive extension points ({@link SENSITIVE_EXTENSION_POINTS}; the code is the
+ * extension point name without `@<major>`, with `-` replaced by `_`).
+ */
+export type SensitiveReason = "secrets" | "public_routes" | "tools" | "hooks" | "ui_embed" | "channel" | "directory" | "identity_source" | "sandbox" | "object_store" | "migration_warnings";
+/** 权限清单里的一项（分组里的一项，或 `added` 里的一个权限键）。 */
+export interface PermissionItem {
+    value: string;
+    sensitive: boolean;
+    /** 敏感时的原因码。 */
+    reason?: SensitiveReason;
+}
+/**
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
+ * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
+ * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ */
+export declare const SENSITIVE_EXTENSION_POINTS: readonly string[];
+/**
+ * 单个权限键是否敏感（`capybara extensions review / approve` 逐项标 `(sensitive)`）：
+ * 与 {@link permissionGroups} 的敏感分组同一套规则。
+ */
+export declare function isSensitivePermissionKey(key: string): boolean;
+/** 权限键逐项的敏感标记与原因（`added` 用；与 {@link permissionGroups} 同一套规则）。 */
+export declare function permissionKeyItems(keys: string[]): PermissionItem[];
+/** 把权限集合整理成分组清单（固定顺序，空组省略）。纯函数。 */
+export declare function permissionGroups(set: PermissionSet): PermissionGroup[];
+/**
+ * 部署级插件状态（后台展示；F-I：副本行存原因，这里推导展示用的状态）。
+ * `dependency`：必需能力没有（加载着的）提供方（F-M：排在 `failed` 之后、`pending_approval` 之前）。
+ */
+export type DeploymentExtensionStatus = "enabled" | "disabled" | "pending_approval" | "pending_config" | "pending_migration" | "converging" | "failed" | "dependency"
+/** The stored package is in the pre-0.1.0 format: reinstall it from a repacked tgz. */
+ | "legacy_format";
+/**
+ * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * （`converging` 收敛中、`pending_migration` 待迁移）。
+ */
+export declare function extensionNeedsAction(status: DeploymentExtensionStatus): boolean;
+/** One item of the admin extension list (`GET /api/v1/admin/extensions`). */
+export interface AdminExtensionView {
+    name: string;
+    version: string;
+    source: ExtensionSource;
+    /** 安装记录的包；配置声明为 null。 */
+    sha256: string | null;
+    status: DeploymentExtensionStatus;
+    /** 安装记录的期望状态；配置声明为 null（始终期望启用）。 */
+    desired: {
+        version: string;
+        sha256: string;
+        state: "enabled" | "disabled";
+    } | null;
+    /** 各副本最近一次上报的加载结果。 */
+    replicas: {
+        replicaId: string;
+        version: string;
+        state: string;
+        reason: string | null;
+        detail: string | null;
+        /** 这一行的版本没加载成、该副本仍在用的旧版本（新版失败 / 待批准时旧版照常）；否则 null。 */
+        servingVersion: string | null;
+        heartbeatAt: string;
+    }[];
+    permissions: PermissionGroup[];
+    /** 相对已批准快照多出 / 少了的权限键（没有快照时全部算新增）。 */
+    added: string[];
+    /** `added` 逐项的敏感标记与原因。 */
+    addedItems: PermissionItem[];
+    removed: string[];
+    /** 见 {@link reviewHash}：网页批准时回传。 */
+    reviewHash: string;
+    /** 任一权限分组敏感（与 `permissions[].sensitive` 一致，界面据此高亮）。 */
+    sensitive: boolean;
+    /**
+     * 安装记录包里迁移 SQL 的审阅警告（与上传时的 `PackageReview.warnings` 相同；配置声明为空）。
+     * 批准前界面同样高亮并要求确认。
+     */
+    warnings: PackageWarning[];
+    snapshot: {
+        version: string;
+        approvedAt: string;
+        approvedBy: string | null;
+        source: "cli" | "auto" | "web" | "bootstrap";
+    } | null;
+    /** 有部署级配置字段。 */
+    configurable: boolean;
+    configValid: boolean;
+    /** 能从部署卸载（只有安装记录，必需的引导插件除外；卸载前须先停用）。 */
+    removable: boolean;
+    /**
+     * A required bootstrap plugin (package ecosystem spec §7): enabled in every org, cannot be
+     * disabled or uninstalled; an enterprise admin may upgrade it.
+     */
+    required: boolean;
+    /** Where the install record came from (`bootstrap` for the bootstrap step); null for config-declared. */
+    installSource: "npm" | "file" | "catalog" | "bootstrap" | null;
+    /**
+     * Why the install record's package cannot be read (bytes missing or corrupt, over the current
+     * size limit; status failed), or the legacy-format message (status `legacy_format`); permissions
+     * are then empty.
+     */
+    error?: string;
+}
+/** Input of {@link deriveExtensionStatus}. */
+export interface StatusInput {
+    source: ExtensionSource;
+    /** 安装记录的期望包与状态；配置声明为 null。 */
+    desired: {
+        sha256: string;
+        state: "enabled" | "disabled";
+    } | null;
+    /** 权限集合未被快照覆盖（F-N：与期望状态无关）。 */
+    pendingApproval: boolean;
+    configValid: boolean;
+    /** 安装记录的 `migrated_sha`。 */
+    migratedSha: string | null;
+    /** 计入的副本行（调用方已按心跳筛过）。 */
+    replicas: {
+        state: string;
+        reason: string | null;
+        sha256: string | null;
+    }[];
+}
+/**
+ * 由期望状态、快照、配置校验、`migrated_sha` 与各副本状态推出部署级状态，优先级：
+ * `failed` > `dependency` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
+ * - 安装记录只看目标包（`desired.sha256`）的副本行：旧包的失败不算；
+ * - 停用的安装记录不看迁移；仍有副本加载着时为 `converging`；
+ * - 配置声明始终期望启用。
+ */
+export declare function deriveExtensionStatus(i: StatusInput): DeploymentExtensionStatus;
+/**
+ * 迁移 SQL 的审阅警告：破坏性语句（`destructive_migration`）、内容不做静态检查的 `DO` 块（`dynamic_sql`，
+ * 块里可以执行任意语句），以及写到插件自己 schema 之外或改权限 / 角色 / 事务的语句（`foreign_schema`，
+ * 见 {@link isForeignSchemaSql}）。都标敏感，不拒绝。
+ */
+export declare function migrationWarnings(files: {
+    file: string;
+    sql: string;
+}[], plugin: string): PackageWarning[];
+/**
+ * 迁移警告的摘要（种类、文件与语句，不含行号：只挪行不算变化）：sha256 前 16 位十六进制；没有警告时为空串。
+ * 记进安装记录包的权限集合（`warningsDigest`，Ruling P4）：权限不变、警告变了（如新增 `GRANT`）同样要重新批准。
+ */
+export declare function warningsDigest(warnings: readonly PackageWarning[]): string;
+/**
+ * 语句是否越出插件自己的 schema（`own`，即 `plugin_<name>`；够用即可，不是 SQL 解析器）：引用内核 schema
+ * `capybara`（`capybara.x` / `"capybara".x`）、写到别的 schema 的对象（`other.x`）、`GRANT` / `REVOKE`、
+ * `CREATE` / `ALTER` / `DROP ROLE|USER|GROUP`、`ALTER DEFAULT PRIVILEGES`、`ALTER … OWNER TO`、
+ * `SET ROLE` / `SET SESSION AUTHORIZATION` / `SET search_path`、`CREATE SCHEMA`、`CREATE EXTENSION`、
+ * `CREATE [OR REPLACE] FUNCTION|PROCEDURE|TRIGGER|EVENT TRIGGER`、`COPY … PROGRAM`，以及事务控制
+ * `COMMIT` / `ROLLBACK` / `BEGIN` / `START TRANSACTION` / `END`（迁移器把每个文件放在一个事务里）。
+ */
+export declare function isForeignSchemaSql(t: string, own: string): boolean;
+/** {@link PackageReview.warnings} 的一项。 */
+export interface PackageWarning {
+    /**
+     * `dynamic_sql`：`DO` 块，块内语句没有检查；`foreign_schema`：写到插件自己 schema 之外、改权限 / 角色、
+     * 建函数 / 触发器或控制事务（{@link isForeignSchemaSql}）。
+     */
+    kind: "destructive_migration" | "dynamic_sql" | "foreign_schema";
+    sensitive: true;
+    /** 迁移文件名（`capybara.migrations` 目录下）。 */
+    file: string;
+    line: number;
+    /** 语句（压成一行，字符串字面量已抹掉）。 */
+    statement: string;
+}

package/dist/extensions/permission-view.js

@@ -0,0 +1,284 @@
+import { createHash } from "node:crypto";
+import { pluginSchemaName } from "../ctx/create-ctx.js";
+import { isDestructiveSql, splitSqlStatements } from "../db/sql-statements.js";
+import { permissionKeys, WARNINGS_KEY_PREFIX } from "./permission-set.js";
+/**
+ * Review digest: the first 16 hex digits of `sha256(permissionKeys(set).join("\n"))`; with migration
+ * warnings their digest (kind, file, line and statement) is folded in, without warnings it equals the
+ * permissions-only digest. The caller sends it back when approving, and approval is refused when it
+ * differs from the one recomputed now (permissions or warnings changed after the review,
+ * `extension.approval_stale`).
+ */
+export function reviewHash(set, warnings = []) {
+    const h = createHash("sha256").update(permissionKeys(set).join("\n"));
+    if (warnings.length > 0) {
+        h.update("\n--warnings--\n");
+        h.update(warnings.map((w) => `${w.kind}\t${w.file}:${w.line}\t${w.statement}`).join("\n"));
+    }
+    return h.digest("hex").slice(0, 16);
+}
+/**
+ * 敏感的能力（D10 + 计划扩展，F-AI）：`sandbox@1` 在部署里执行任意命令、`object-store@1` 保管全部附件与插件包（D10）；
+ * `channel@1` 收到组织在 IM 里的对话内容（Ruling A33）、`directory@1` 能把人加进组织（并为其建账号、建身份）、
+ * `identity-source@1` 决定谁能登录成哪个账号。插件提供其中任何一个时，「提供」一组标为敏感，
+ * 后台插件列表的 `sensitive` 为真，须企业管理员批准。只影响展示，不改权限快照的键。
+ */
+export const SENSITIVE_EXTENSION_POINTS = [
+    "channel@1",
+    "directory@1",
+    "identity-source@1",
+    "sandbox@1",
+    "object-store@1",
+];
+/** 总是敏感的类别。 */
+const ALWAYS_SENSITIVE = new Set([
+    "secrets",
+    "publicRoutes",
+    "tools",
+    "hooks",
+]);
+const CATEGORY_REASON = {
+    secrets: "secrets",
+    publicRoutes: "public_routes",
+    tools: "tools",
+    hooks: "hooks",
+};
+/**
+ * Why an item in a category is sensitive (undefined when it is not; shared by the grouped list, the
+ * per-item `added` and the CLI markers): secrets, public routes, tools and hooks are always
+ * sensitive; {@link SENSITIVE_EXTENSION_POINTS} in "provides"; embedded apps (`embed:<id>`) in "UI".
+ */
+function itemReason(category, item) {
+    // storage 不算敏感：ctx.storage 的键由内核加前缀 `plugins/<插件>/<orgId>/`，插件只能读写自己的前缀
+    if (category === "provides") {
+        return SENSITIVE_EXTENSION_POINTS.includes(item)
+            ? item.split("@")[0].replaceAll("-", "_")
+            : undefined;
+    }
+    if (category === "ui")
+        return item.startsWith("embed:") ? "ui_embed" : undefined;
+    return ALWAYS_SENSITIVE.has(category) ? CATEGORY_REASON[category] : undefined;
+}
+const itemOf = (category, value) => {
+    const reason = itemReason(category, value);
+    return reason === undefined ? { value, sensitive: false } : { value, sensitive: true, reason };
+};
+/** 权限键（{@link permissionKeys} 的格式）所属的类别与展示项；不属于敏感判定相关类别的返回 null。 */
+function keyItem(key) {
+    const after = (prefix) => (key.startsWith(prefix) ? key.slice(prefix.length) : null);
+    if (key === "permissions.secrets")
+        return { category: "secrets", item: "secret store" };
+    if (/^config\.(deployment|org)\.secret:/.test(key))
+        return { category: "secrets", item: key.slice(key.indexOf(":") + 1) };
+    const table = [
+        ["provides:", "provides", ""],
+        ["permissions.http.public:", "publicRoutes", ""],
+        ["permissions.tools:", "tools", ""],
+        ["permissions.hooks:", "hooks", ""],
+        ["permissions.hooks.policy:", "hooks", "policy:"],
+        ["ui.embed:", "ui", "embed:"],
+        ["ui.view:", "ui", "view:"],
+    ];
+    for (const [prefix, category, itemPrefix] of table) {
+        const rest = after(prefix);
+        if (rest !== null)
+            return { category, item: `${itemPrefix}${rest}` };
+    }
+    return null;
+}
+/**
+ * 单个权限键是否敏感（`capybara extensions review / approve` 逐项标 `(sensitive)`）：
+ * 与 {@link permissionGroups} 的敏感分组同一套规则。
+ */
+export function isSensitivePermissionKey(key) {
+    if (key.startsWith(WARNINGS_KEY_PREFIX))
+        return true;
+    const k = keyItem(key);
+    return k !== null && itemReason(k.category, k.item) !== undefined;
+}
+/** 权限键逐项的敏感标记与原因（`added` 用；与 {@link permissionGroups} 同一套规则）。 */
+export function permissionKeyItems(keys) {
+    return keys.map((value) => {
+        // 迁移警告的摘要（Ruling P4）：警告本身见 `warnings`
+        if (value.startsWith(WARNINGS_KEY_PREFIX)) {
+            return { value, sensitive: true, reason: "migration_warnings" };
+        }
+        const k = keyItem(value);
+        if (k === null)
+            return { value, sensitive: false };
+        const reason = itemReason(k.category, k.item);
+        return reason === undefined ? { value, sensitive: false } : { value, sensitive: true, reason };
+    });
+}
+/** 把权限集合整理成分组清单（固定顺序，空组省略）。纯函数。 */
+export function permissionGroups(set) {
+    const p = set.permissions;
+    // 旧快照没有 ui（按空处理）
+    const ui = p.ui ?? { views: [], embeds: [] };
+    const secretFields = [...set.config.deployment, ...set.config.org]
+        .filter((f) => f.secret)
+        .map((f) => f.path || "<root>");
+    const configFields = ["deployment", "org"].flatMap((level) => set.config[level].map((f) => `${level}:${f.path || "<root>"}`));
+    const secretItems = [...(p.secrets ? ["secret store"] : []), ...secretFields];
+    const groups = [
+        {
+            category: "provides",
+            items: set.provides,
+        },
+        { category: "requires", items: set.requires },
+        { category: "optional", items: set.optional },
+        { category: "config", items: configFields },
+        { category: "tables", items: set.tables },
+        { category: "secrets", items: secretItems },
+        { category: "storage", items: p.storage ? ["storage"] : [] },
+        {
+            category: "http",
+            items: p.http.filter((r) => !r.public).map((r) => `${r.method} ${r.path}`),
+        },
+        {
+            category: "publicRoutes",
+            items: p.http.filter((r) => r.public).map((r) => `${r.method} ${r.path}`),
+        },
+        { category: "tools", items: p.tools },
+        { category: "hooks", items: [...p.hooks, ...(p.policyHooks ?? []).map((h) => `policy:${h}`)] },
+        {
+            category: "models",
+            items: p.models.map((m) => `${m.purpose} (${m.kind})`),
+        },
+        { category: "network", items: p.network },
+        {
+            category: "ui",
+            items: [...ui.views.map((v) => `view:${v}`), ...ui.embeds.map((e) => `embed:${e}`)],
+        },
+    ];
+    return groups
+        .filter((g) => g.items.length > 0)
+        .map((g) => {
+        const entries = g.items.map((i) => itemOf(g.category, i));
+        return { ...g, sensitive: entries.some((e) => e.sensitive), entries };
+    });
+}
+/**
+ * 需要企业管理员处理的状态（后台概览「需要处理的插件」）：待批准、待配置、失败、依赖缺失，以及副本不一致
+ * （`converging` 收敛中、`pending_migration` 待迁移）。
+ */
+export function extensionNeedsAction(status) {
+    return status !== "enabled" && status !== "disabled";
+}
+/**
+ * 由期望状态、快照、配置校验、`migrated_sha` 与各副本状态推出部署级状态，优先级：
+ * `failed` > `dependency` > `pending_approval` > `pending_config` > `pending_migration` > `converging` > `enabled` / `disabled`。
+ * - 安装记录只看目标包（`desired.sha256`）的副本行：旧包的失败不算；
+ * - 停用的安装记录不看迁移；仍有副本加载着时为 `converging`；
+ * - 配置声明始终期望启用。
+ */
+export function deriveExtensionStatus(i) {
+    const target = i.desired?.sha256 ?? null;
+    const rows = target === null ? i.replicas : i.replicas.filter((r) => r.sha256 === target);
+    if (rows.some((r) => r.state === "failed"))
+        return "failed";
+    if (rows.some((r) => r.reason === "dependency" && (r.state === "pending" || r.state === "unloaded")))
+        return "dependency";
+    if (i.pendingApproval)
+        return "pending_approval";
+    if (!i.configValid)
+        return "pending_config";
+    const wantLoaded = i.desired === null || i.desired.state === "enabled";
+    if (!wantLoaded)
+        return i.replicas.some((r) => r.state === "loaded") ? "converging" : "disabled";
+    if (i.desired !== null && i.migratedSha !== i.desired.sha256)
+        return "pending_migration";
+    if (rows.some((r) => r.state === "pending" && r.reason === "migration"))
+        return "pending_migration";
+    const done = i.replicas.length > 0 &&
+        i.replicas.every((r) => r.state === "loaded" && (target === null || r.sha256 === target));
+    return done ? "enabled" : "converging";
+}
+/**
+ * 迁移 SQL 的审阅警告：破坏性语句（`destructive_migration`）、内容不做静态检查的 `DO` 块（`dynamic_sql`，
+ * 块里可以执行任意语句），以及写到插件自己 schema 之外或改权限 / 角色 / 事务的语句（`foreign_schema`，
+ * 见 {@link isForeignSchemaSql}）。都标敏感，不拒绝。
+ */
+export function migrationWarnings(files, plugin) {
+    const own = pluginSchemaName(plugin);
+    return files.flatMap((m) => splitSqlStatements(m.sql).flatMap((st) => {
+        const base = { sensitive: true, file: m.file, line: st.line, statement: st.text };
+        if (/^DO\b/i.test(st.text))
+            return [{ kind: "dynamic_sql", ...base }];
+        if (isForeignSchemaSql(withQuoted(st), own))
+            return [{ kind: "foreign_schema", ...base }];
+        if (isDestructiveSql(st.text))
+            return [{ kind: "destructive_migration", ...base }];
+        return [];
+    }));
+}
+/**
+ * 迁移警告的摘要（种类、文件与语句，不含行号：只挪行不算变化）：sha256 前 16 位十六进制；没有警告时为空串。
+ * 记进安装记录包的权限集合（`warningsDigest`，Ruling P4）：权限不变、警告变了（如新增 `GRANT`）同样要重新批准。
+ */
+export function warningsDigest(warnings) {
+    if (warnings.length === 0)
+        return "";
+    return createHash("sha256")
+        .update(warnings.map((w) => `${w.kind}\t${w.file}\t${w.statement}`).join("\n"))
+        .digest("hex")
+        .slice(0, 16);
+}
+const IDENT_RE = `(?:"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*)`;
+const TARGET_RE = String.raw `(${IDENT_RE}(?:\s*\.\s*${IDENT_RE})?)`;
+/**
+ * Targets of write statements (creating / altering / dropping tables, indexes, views and so on, and
+ * the table of INSERT / UPDATE / DELETE / TRUNCATE / MERGE / COPY).
+ */
+const WRITE_TARGETS = [
+    new RegExp(String.raw `^INSERT\s+INTO\s+${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^UPDATE\s+(?:ONLY\s+)?${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^DELETE\s+FROM\s+(?:ONLY\s+)?${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^TRUNCATE\s+(?:TABLE\s+)?(?:ONLY\s+)?${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^MERGE\s+INTO\s+${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^COPY\s+${TARGET_RE}`, "i"),
+    new RegExp(String.raw `^(?:CREATE|ALTER|DROP)\s+(?:OR\s+REPLACE\s+)?(?:(?:GLOBAL|LOCAL)\s+)?(?:(?:TEMP|TEMPORARY|UNLOGGED|MATERIALIZED|UNIQUE|FOREIGN)\s+)?(?:TABLE|INDEX|VIEW|SEQUENCE|TYPE|DOMAIN)\s+(?:CONCURRENTLY\s+)?(?:IF\s+(?:NOT\s+)?EXISTS\s+)?(?:ONLY\s+)?${TARGET_RE}`, "i"),
+    // CREATE INDEX … ON <表>
+    new RegExp(String.raw `^CREATE\s+(?:UNIQUE\s+)?INDEX\b.*?\bON\s+(?:ONLY\s+)?${TARGET_RE}`, "i"),
+];
+/** 标识符规范化：带引号的去引号（`""` 还原），不带引号的转小写。 */
+const normIdent = (s) => s.startsWith('"') ? s.slice(1, -1).replaceAll('""', '"') : s.toLowerCase();
+/** 写语句的目标里有带 schema、且不是 `own` 的。 */
+function writesOtherSchema(t, own) {
+    for (const re of WRITE_TARGETS) {
+        const m = re.exec(t);
+        if (!m)
+            continue;
+        const parts = m[1].match(new RegExp(IDENT_RE, "g")) ?? [];
+        if (parts.length === 2 && normIdent(parts[0]) !== own)
+            return true;
+    }
+    return false;
+}
+/** 把语句 `text` 里抹掉的双引号标识符填回去（`"capybara".x` 这类引用才看得见）。 */
+function withQuoted(st) {
+    let k = 0;
+    return st.text.replace(/""/g, () => `"${st.quoted[k++] ?? ""}"`);
+}
+/**
+ * 语句是否越出插件自己的 schema（`own`，即 `plugin_<name>`；够用即可，不是 SQL 解析器）：引用内核 schema
+ * `capybara`（`capybara.x` / `"capybara".x`）、写到别的 schema 的对象（`other.x`）、`GRANT` / `REVOKE`、
+ * `CREATE` / `ALTER` / `DROP ROLE|USER|GROUP`、`ALTER DEFAULT PRIVILEGES`、`ALTER … OWNER TO`、
+ * `SET ROLE` / `SET SESSION AUTHORIZATION` / `SET search_path`、`CREATE SCHEMA`、`CREATE EXTENSION`、
+ * `CREATE [OR REPLACE] FUNCTION|PROCEDURE|TRIGGER|EVENT TRIGGER`、`COPY … PROGRAM`，以及事务控制
+ * `COMMIT` / `ROLLBACK` / `BEGIN` / `START TRANSACTION` / `END`（迁移器把每个文件放在一个事务里）。
+ */
+export function isForeignSchemaSql(t, own) {
+    return (/(?:^|[^\w$"])"?capybara"?\s*\./i.test(t) ||
+        writesOtherSchema(t, own) ||
+        /^ALTER\b.*\bOWNER\s+TO\b/i.test(t) ||
+        /^SET\s+(?:SESSION\s+|LOCAL\s+)?search_path\b/i.test(t) ||
+        /^CREATE\s+(?:SCHEMA|EXTENSION)\b/i.test(t) ||
+        /^COPY\b.*\bPROGRAM\b/i.test(t) ||
+        /^(?:GRANT|REVOKE)\b/i.test(t) ||
+        /^(?:CREATE|ALTER|DROP)\s+(?:ROLE|USER|GROUP)\b/i.test(t) ||
+        /^ALTER\s+DEFAULT\s+PRIVILEGES\b/i.test(t) ||
+        /^SET\s+(?:SESSION\s+|LOCAL\s+)?(?:ROLE|SESSION\s+AUTHORIZATION)\b/i.test(t) ||
+        /^CREATE\s+(?:OR\s+REPLACE\s+)?(?:CONSTRAINT\s+)?(?:FUNCTION|PROCEDURE|TRIGGER|EVENT\s+TRIGGER)\b/i.test(t) ||
+        /^(?:COMMIT|ROLLBACK|BEGIN|START\s+TRANSACTION|END|ABORT)\b/i.test(t));
+}

package/dist/extensions/registry.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionInstance } from "./instance.js";
+/**
+ * 本进程生效的插件实例（按插件名，一名一个）。顺序 = 首次激活的顺序（宿主按依赖拓扑序加载；
+ * 替换同名实例保持原位置）。只是本进程的视图：跨副本的期望状态在 PG（安装记录），由各副本自己 reconcile。
+ */
+export declare class ExtensionRegistry {
+    private readonly instances;
+    private readonly listeners;
+    private rev;
+    /** 原子替换：登记新实例，返回被替换的旧实例（由调用方 dispose）。 */
+    activate(inst: ExtensionInstance): ExtensionInstance | undefined;
+    /** 摘下：返回被摘下的实例（由调用方 dispose）；不在时返回 undefined。 */
+    deactivate(name: string): ExtensionInstance | undefined;
+    current(name: string): ExtensionInstance | undefined;
+    all(): ExtensionInstance[];
+    /** 每次激活 / 摘下加一（给按版本缓存的派生视图用，如插件路由表）。 */
+    revision(): number;
+    /**
+     * 订阅变化（激活 / 替换 / 摘下，参数为插件名）。只通知本进程的消费方（渠道 supervisor、界面等），不跨副本。
+     * 监听函数同步调用，抛错被吞掉（不影响注册表与其他监听方）。返回取消订阅函数。
+     */
+    onChange(listener: (name: string) => void): () => void;
+    private changed;
+}

package/dist/extensions/registry.js

@@ -0,0 +1,56 @@
+/**
+ * 本进程生效的插件实例（按插件名，一名一个）。顺序 = 首次激活的顺序（宿主按依赖拓扑序加载；
+ * 替换同名实例保持原位置）。只是本进程的视图：跨副本的期望状态在 PG（安装记录），由各副本自己 reconcile。
+ */
+export class ExtensionRegistry {
+    instances = new Map();
+    listeners = new Set();
+    rev = 0;
+    /** 原子替换：登记新实例，返回被替换的旧实例（由调用方 dispose）。 */
+    activate(inst) {
+        const old = this.instances.get(inst.name);
+        this.instances.set(inst.name, inst);
+        this.changed(inst.name);
+        return old;
+    }
+    /** 摘下：返回被摘下的实例（由调用方 dispose）；不在时返回 undefined。 */
+    deactivate(name) {
+        const old = this.instances.get(name);
+        if (!old)
+            return undefined;
+        this.instances.delete(name);
+        this.changed(name);
+        return old;
+    }
+    current(name) {
+        return this.instances.get(name);
+    }
+    all() {
+        return [...this.instances.values()];
+    }
+    /** 每次激活 / 摘下加一（给按版本缓存的派生视图用，如插件路由表）。 */
+    revision() {
+        return this.rev;
+    }
+    /**
+     * 订阅变化（激活 / 替换 / 摘下，参数为插件名）。只通知本进程的消费方（渠道 supervisor、界面等），不跨副本。
+     * 监听函数同步调用，抛错被吞掉（不影响注册表与其他监听方）。返回取消订阅函数。
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    changed(name) {
+        this.rev += 1;
+        for (const l of [...this.listeners]) {
+            try {
+                l(name);
+            }
+            catch {
+                // 监听方自己记日志；这里不让它影响注册表
+            }
+        }
+    }
+}

package/dist/extensions/resolve.d.ts

@@ -0,0 +1,12 @@
+import { type ExtensionManifest } from "@capybara-hq/plugin-sdk";
+/** 插件依赖解析失败（信息列出插件名与能力名）。 */
+export declare class ExtensionResolveError extends Error {
+    constructor(message: string);
+}
+/**
+ * 校验 sdk 范围、依赖满足度、单选能力唯一性与无环，返回按依赖拓扑排序后的列表（同层保持输入顺序）。
+ * `requires` 缺提供方报错；`optional` 缺提供方不报错，但存在的提供方与 `requires` 一样参与排序与环检测。
+ * 声明了 `permissions.storage` 的插件隐含依赖 `object-store@1`（中转能力，不能 `requires`）：提供方排在它前面；
+ * 缺提供方不在这里报错，由权限闸门把它列为 pending（见 approvals.ts）。
+ */
+export declare function resolveExtensions(manifests: ExtensionManifest[], sdkVersion: string): ExtensionManifest[];

package/dist/extensions/resolve.js

@@ -0,0 +1,71 @@
+import { EXTENSION_POINT_CARDINALITY, OBJECT_STORE_EXTENSION_POINT, parseExtensionPoint, } from "@capybara-hq/plugin-sdk";
+import semver from "semver";
+/** 插件依赖解析失败（信息列出插件名与能力名）。 */
+export class ExtensionResolveError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExtensionResolveError";
+    }
+}
+/**
+ * 校验 sdk 范围、依赖满足度、单选能力唯一性与无环，返回按依赖拓扑排序后的列表（同层保持输入顺序）。
+ * `requires` 缺提供方报错；`optional` 缺提供方不报错，但存在的提供方与 `requires` 一样参与排序与环检测。
+ * 声明了 `permissions.storage` 的插件隐含依赖 `object-store@1`（中转能力，不能 `requires`）：提供方排在它前面；
+ * 缺提供方不在这里报错，由权限闸门把它列为 pending（见 approvals.ts）。
+ */
+export function resolveExtensions(manifests, sdkVersion) {
+    const seen = new Set();
+    for (const m of manifests) {
+        if (seen.has(m.name))
+            throw new ExtensionResolveError(`plugin ${m.name}: loaded more than once`);
+        seen.add(m.name);
+        if (!semver.satisfies(sdkVersion, m.sdk)) {
+            throw new ExtensionResolveError(`plugin ${m.name}: sdk range "${m.sdk}" is not satisfied by SDK_VERSION ${sdkVersion}`);
+        }
+    }
+    const providers = new Map();
+    for (const m of manifests) {
+        for (const cap of m.provides)
+            providers.set(cap, [...(providers.get(cap) ?? []), m]);
+    }
+    for (const [cap, list] of providers) {
+        if (EXTENSION_POINT_CARDINALITY[parseExtensionPoint(cap).name] === "single" &&
+            list.length > 1) {
+            throw new ExtensionResolveError(`extension point ${cap} is single-provider but provided by: ${list.map((p) => p.name).join(", ")}`);
+        }
+    }
+    for (const m of manifests) {
+        for (const cap of m.requires ?? []) {
+            if (!providers.has(cap)) {
+                throw new ExtensionResolveError(`plugin ${m.name}: required extension point ${cap} has no provider`);
+            }
+        }
+    }
+    const done = new Set();
+    const visiting = [];
+    const out = [];
+    const visit = (m) => {
+        if (done.has(m.name))
+            return;
+        if (visiting.includes(m.name)) {
+            const cycle = [...visiting.slice(visiting.indexOf(m.name)), m.name].join(" -> ");
+            throw new ExtensionResolveError(`dependency cycle: ${cycle}`);
+        }
+        visiting.push(m.name);
+        for (const cap of [...(m.requires ?? []), ...(m.optional ?? [])]) {
+            for (const p of providers.get(cap) ?? [])
+                visit(p);
+        }
+        if (m.permissions?.storage) {
+            for (const p of providers.get(OBJECT_STORE_EXTENSION_POINT) ?? [])
+                if (p !== m)
+                    visit(p);
+        }
+        visiting.pop();
+        done.add(m.name);
+        out.push(m);
+    };
+    for (const m of manifests)
+        visit(m);
+    return out;
+}