berry-agent 0.1.0-alpha.1

package/dist/sdk/index.js

@@ -0,0 +1,22 @@
+/**
+ * core:sdk 件域（批 13e 起域——03 §10.6 件身份条：HTTP+SSE 传输与 MCP
+ * server 包装归本件；协议核心与 stdio 归宿主/channels 侧既有）。
+ *
+ * 本笔（13e-1）= 契约先行：HTTP 面端点词面（03 §10.6 批 13e 落码定形注①）
+ * + 开面配置形（07 §5 serve 旗标族落码定名——sock 缺省接入点/TCP 可选位/
+ * 凭证双载体）+ 三防线判定器与 token 生成（10.4 回环钉死条款同律复用 +
+ * 差异面④ Host 扩集谓词）。传输实装（node:http 微路由 + SSE + 一核多流
+ * 扇出）随 13e-2 兑现（本域 http 件）；daemon 编舞（pid/sock/log 三足迹 +
+ * serve status/stop）随 13e-3；MCP server 包装（行帧 JSON-RPC 反向位、
+ * 工具面收窄两件——`berry-agent`/`berry-agent-reply`）随 13f 兑现（本域
+ * mcp 件）。
+ *
+ * 装配纪律（件不 import 宿主实现——webui claim 桥晚绑同款）：协议核经
+ * channels 公开面消费（SdkWireDeps 由宿主装配桥注入），本域零 host 依赖。
+ */
+export * from './types.js';
+export * from './security.js';
+export * from './http.js';
+export * from './mcp.js';
+export * from './plugin-routes.js';
+export * from './plugin-route-registry.js';

package/dist/sdk/mcp.js

@@ -0,0 +1,289 @@
+import { createSdkBackend, splitWireLines, validateSdkRequest, } from '../channels/index.js';
+/* ---------------- MCP 协议常量（行帧 JSON-RPC 2.0——10.1 反向位同集） ---------------- */
+/** 已知 protocolVersion 集（回显制——请求值在集内即回显） */
+const MCP_KNOWN_VERSIONS = ['2024-11-05', '2025-03-26', '2025-06-18'];
+/** 服务端缺省 protocolVersion（请求值不在已知集时回本值） */
+const MCP_DEFAULT_VERSION = '2025-06-18';
+/** JSON-RPC 2.0 错误码（协议错档——业务错走工具结果 isError 位不占此面） */
+const JSONRPC_PARSE_ERROR = -32700;
+const JSONRPC_METHOD_NOT_FOUND = -32601;
+const JSONRPC_INVALID_PARAMS = -32602;
+const JSONRPC_INTERNAL_ERROR = -32603;
+/** 会话发起/续接工具名（codex `codex` 形镜像——对外声明值位） */
+export const MCP_PROMPT_TOOL_NAME = 'berry-agent';
+/** 回复轮询工具名（codex `codex-reply` 形镜像） */
+export const MCP_POLL_TOOL_NAME = 'berry-agent-reply';
+/** 工具面收窄两件（tools/list 应答单源——inputSchema 手写字面静态声明） */
+const MCP_TOOLS = [
+    {
+        name: MCP_PROMPT_TOOL_NAME,
+        description: '向 berry-agent 会话发起或续接一条消息（异步档：受理即回执——回复增量经 berry-agent-reply 轮询获取）',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: '用户消息正文' },
+                sessionId: { type: 'string', description: '续接会话句柄——缺席即新建会话' },
+                messageId: {
+                    type: 'string',
+                    description: '幂等键（同键同内容重发收执 duplicate 不重跑）——缺席则每次全新',
+                },
+            },
+            required: ['message'],
+        },
+    },
+    {
+        name: MCP_POLL_TOOL_NAME,
+        description: '轮询会话回复增量（durable 投影——含消息定稿与 run 终态事件；lastSeq 为续读位）',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sessionId: { type: 'string', description: '会话句柄' },
+                since: {
+                    type: 'number',
+                    description: '已收末条 seq（窗口 (since, 高水位]）——缺席 -1 从头取全窗',
+                },
+            },
+            required: ['sessionId'],
+        },
+    },
+];
+/**
+ * 起 MCP server 面：一行一 JSON-RPC 消息（请求/通知）进、一行一应答出。
+ *
+ * 应答写出纪律：MCP 应答帧小量低频（一请求一应答），Node 流内缓冲即背压
+ * 界——不设独立队列（serve 直写面的有界队列背压机械不在此复制，量级不配）。
+ */
+export function runMcpFace(options) {
+    const log = options.log ?? (() => { });
+    // 收集式 sink：MCP 形请求/应答档——无订阅即无直播帧流；应答帧在
+    // handleRequest 同步事务内收齐、由工具调用处取走翻译成 MCP 工具结果
+    //（协议核应答帧不达 MCP 线——包装层只投影不转发）。
+    // capturing 位 = 零直播面的传输边界执法：prompt 自动订阅（13b 落码定形）
+    // 会让在飞 run 的活体帧流入本 sink——无 MCP 直播线可承载即弃（返回 true
+    // 视为写达，出站队列恒空——背压机械不触发）；仅在 roundTrip 事务内收帧
+    let collected = [];
+    let capturing = false;
+    const sink = {
+        write: (frame) => {
+            if (capturing)
+                collected.push(frame);
+            return true;
+        },
+    };
+    // 协议核单源（admit/先决门/深校验后的受理全在核内；MCP 形无连接级
+    // hello——noDelta 无承载位，核选项全缺省）
+    const backend = createSdkBackend({ ...options.bridge, sink });
+    // 未携幂等键的 prompt 计数（「幂等语义未申请即不虚构」——每次全新）
+    let unkeyedSeq = 0;
+    /**
+     * 经协议核受理一请求并同步取应答帧（映射层薄——全部受理语义单源在核）。
+     * 应答缺席 = 核内不变式破（理论不达）——由 {@link translate} 出内部错。
+     */
+    const roundTrip = (req) => {
+        collected = [];
+        capturing = true;
+        try {
+            backend.core.handleRequest(req);
+        }
+        finally {
+            capturing = false; // 事务外活体帧一律弃（零直播面——见 sink 位注）
+        }
+        const frames = collected;
+        collected = [];
+        return frames[0];
+    };
+    /** 写一行 JSON-RPC 消息 */
+    const writeMessage = (msg) => {
+        options.io.output.write(`${JSON.stringify(msg)}\n`);
+    };
+    /** JSON-RPC 成功应答（请求 id 原样回联——string/number 两形皆透传） */
+    const writeResult = (id, result) => {
+        writeMessage({ jsonrpc: '2.0', id, result });
+    };
+    const writeError = (id, code, message) => {
+        writeMessage({ jsonrpc: '2.0', id, error: { code, message } });
+    };
+    /** tools/call 工具结果速记（isError 位 = 业务错两分档——非 JSON-RPC error） */
+    const writeToolResult = (id, text, isError = false) => {
+        writeResult(id, { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) });
+    };
+    /** 应答帧 → MCP 工具结果翻译（ack/entries/error 三投影位——两动词共用） */
+    const translate = (frame, id, sinceDefault = -1) => {
+        if (frame === undefined) {
+            writeError(id, JSONRPC_INTERNAL_ERROR, '协议核应答缺席（内部不变式破）');
+            return;
+        }
+        if (frame.kind === 'error') {
+            writeToolResult(id, JSON.stringify({ code: frame.code, message: frame.message }), true);
+            return;
+        }
+        if (frame.kind === 'ack') {
+            // ack 投影（受理回执——异步档的会话句柄获取位）
+            writeToolResult(id, JSON.stringify({
+                sessionId: frame.sessionId,
+                messageId: frame.messageId,
+                duplicate: frame.duplicate,
+                ...(frame.routedChannel !== undefined ? { routedChannel: frame.routedChannel } : {}),
+                highWaterSeq: frame.highWaterSeq,
+            }));
+            return;
+        }
+        if (frame.kind === 'entries') {
+            // 空窗 lastSeq = 续读位原样回显（无进展不虚报）
+            const lastSeq = frame.entries.length > 0 ? frame.entries[frame.entries.length - 1].seq : sinceDefault;
+            writeToolResult(id, JSON.stringify({ sessionId: frame.sessionId, entries: frame.entries, lastSeq }));
+            return;
+        }
+        // 其余应答帧形理论不达（两动词只产 ack/entries/error）——内部错如实出
+        writeError(id, JSONRPC_INTERNAL_ERROR, `意外应答帧形 ${String(frame.kind)}`);
+    };
+    /** 工具参数 → 深校验请求（同源校验器单源——stdio 解码位/HTTP 体校验位同款） */
+    const validate = (id, raw) => {
+        const validated = validateSdkRequest(raw);
+        if (!validated.ok) {
+            writeToolResult(id, `参数不符：${validated.reason}`, true);
+            return { ok: false };
+        }
+        return { ok: true, value: validated.value };
+    };
+    /** 工具调用 → 协议核动词映射（两件收窄面） */
+    const callTool = (id, name, args) => {
+        if (name === MCP_PROMPT_TOOL_NAME) {
+            // 幂等键调用方自选律：缺席 = 计数器形全新键（幂等语义未申请即不虚构）
+            const messageId = typeof args?.messageId === 'string' && args.messageId !== '' ? args.messageId : `mcp-${++unkeyedSeq}`;
+            const v = validate(id, {
+                verb: 'prompt',
+                messageId,
+                content: args?.message,
+                ...(typeof args?.sessionId === 'string' ? { sessionId: args.sessionId } : {}),
+            });
+            if (!v.ok)
+                return;
+            translate(roundTrip(v.value), id);
+            return;
+        }
+        if (name === MCP_POLL_TOOL_NAME) {
+            // since 缺省 -1 从头哨兵（cursor.ts resolveLiveStart 同款语义）
+            const since = typeof args?.since === 'number' ? args.since : -1;
+            const v = validate(id, { verb: 'getEntries', sessionId: args?.sessionId, since });
+            if (!v.ok)
+                return;
+            if (v.value.verb !== 'getEntries')
+                return; // 构造面恒真——纯类型收窄位
+            // 分页跟尽义务在调用方（05 §3.4）——本面即调用方：nextCursor 在场即
+            // 续读（v1 装配桥并页兑现零游标——环体防御性在场，正常零次执行；
+            // 帽 100 防环游标死循环）
+            let frame = roundTrip(v.value);
+            let hops = 0;
+            while (frame !== undefined && frame.kind === 'entries' && frame.nextCursor !== undefined && hops < 100) {
+                hops++;
+                const more = roundTrip({ ...v.value, cursor: frame.nextCursor });
+                if (more === undefined || more.kind !== 'entries')
+                    break;
+                frame = { ...more, entries: [...frame.entries, ...more.entries] };
+            }
+            translate(frame, id, since);
+            return;
+        }
+        // 未知工具 = 协议参数错（非业务错——工具面两件闭集外即调用方笔误）
+        writeError(id, JSONRPC_INVALID_PARAMS, `未知工具 ${String(name)}（工具面 = ${MCP_PROMPT_TOOL_NAME} / ${MCP_POLL_TOOL_NAME}）`);
+    };
+    /** 单条 JSON-RPC 消息路由（请求/通知两分） */
+    const handleMessage = (msg) => {
+        if (typeof msg !== 'object' || msg === null)
+            return; // 帧形不理（无 id 可应答）
+        const { method, id, params } = msg;
+        // 通知（id 缺席）零应答——notifications/initialized 等一律静默收执
+        if (id === undefined)
+            return;
+        switch (method) {
+            case 'initialize': {
+                const requested = params?.protocolVersion;
+                const version = typeof requested === 'string' && MCP_KNOWN_VERSIONS.includes(requested)
+                    ? requested // 已知集回显（客户端版本优先）
+                    : MCP_DEFAULT_VERSION; // 未知/缺席 → 服务端缺省
+                writeResult(id, {
+                    protocolVersion: version,
+                    capabilities: { tools: {} }, // 工具面在场（listChanged 不发——静态两件）
+                    serverInfo: options.serverInfo,
+                });
+                return;
+            }
+            case 'ping':
+                writeResult(id, {});
+                return;
+            case 'tools/list':
+                writeResult(id, { tools: MCP_TOOLS });
+                return;
+            case 'tools/call': {
+                const p = (params ?? {});
+                callTool(id, p.name, typeof p.arguments === 'object' && p.arguments !== null
+                    ? p.arguments
+                    : undefined);
+                return;
+            }
+            default:
+                writeError(id, JSONRPC_METHOD_NOT_FOUND, `未知方法 ${String(method)}`);
+        }
+    };
+    // —— 收场单次性（EOF 优雅 0 / 输入输出面坏死 1）——
+    let settled = false;
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    const finish = (code) => {
+        if (settled)
+            return;
+        settled = true;
+        options.io.input.removeListener('data', onData);
+        options.io.input.removeListener('end', onEnd);
+        options.io.input.removeListener('close', onEnd);
+        options.io.input.removeListener('error', onInputError);
+        options.io.output.removeListener('error', onOutputError);
+        backend.dispose();
+        resolveDone(code);
+    };
+    // —— 入站环：分帧（行安全同源件）→ JSON 解析 → 消息路由 ——
+    let remainder = '';
+    const onData = (chunk) => {
+        if (settled)
+            return;
+        const split = splitWireLines(chunk, remainder);
+        remainder = split.remainder;
+        for (const line of split.lines) {
+            if (line.length === 0)
+                continue; // 空行不理
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                // 坏行：JSON-RPC 规范形应答（id null——解析失败无从取 id）
+                writeError(null, JSONRPC_PARSE_ERROR, '行不是合法 JSON');
+                continue;
+            }
+            handleMessage(msg);
+        }
+    };
+    const onEnd = () => finish(0); // EOF = 调用方收线（对端 agent 退出）
+    const onInputError = (err) => {
+        log(`stdin 异常：${err.message}`);
+        finish(1);
+    };
+    const onOutputError = (err) => {
+        log(`stdout 异常：${err.message}`);
+        finish(1);
+    };
+    options.io.input.setEncoding?.('utf8');
+    options.io.input.on('data', onData);
+    options.io.input.on('end', onEnd);
+    options.io.input.on('close', onEnd);
+    options.io.input.on('error', onInputError);
+    options.io.output.on('error', onOutputError);
+    return {
+        backend: backend.backend,
+        done,
+        dispose: () => finish(0), // 宿主 closer 消费（信号路优雅档）；幂等
+    };
+}

package/dist/sdk/plugin-route-registry.js

@@ -0,0 +1,126 @@
+/**
+ * sdk/plugin-route-registry — 插件道路由受理器真身（U5-2 装配+时序笔）。
+ *
+ * 03 §10.6 U5 定形注「时序缝定形」段的码面兑现：**host-owned 待注册路由
+ * registry**（受理与挂载两时点解耦——「插件 boot 先于 HTTP 面存在」三入口
+ * 结构性缝的正解）。受理动作恒 apply 期入本账（装载窗执法在前）；挂载由
+ * 两路 replay：
+ * - **构造期路**：daemon / TUI `--port` / serve 前台三入口开面时
+ *   `snapshot()` 快照注入 `SdkHttpFaceOptions.routes` 位；
+ * - **晚注册路**：面已开后受理（/reload 换代重走受理序——受理窗装载期
+ *   恒先于或外在于开面时点，两序皆可达）经 `attachFace` 持有的活面
+ *   `face.register` 晚注册位（claim 桥同款）。
+ *
+ * 受理序（§2.2 第十三面全链）= 装载窗（`PLUGIN_WINDOW_CLOSED`——
+ * registerOAuthFlow〔c-6〕/registerSummarizer〔U4〕同律窗先于门）→ 门检
+ * （`adjudicateCapabilityDoor`——assertDoor 第二落地点；core: 官方件直开
+ * 豁免〔§4.6 判据：装配即用户意图〕但审计照记——「豁免免的是门不是账」
+ * triggers 同律）→ 纯函数裁决（`adjudicatePluginRoute`——SDK_ROUTE_ 四码）
+ * → 查重（面在场走 face.register 既有 method+path 双键普通 Error；缺席态
+ * 账内同形 Error——与 core: 道同表同律零新码）→ 受理入账（面在场附带
+ * 挂载）→ `capability/used` 审计恰一笔（05 §1.1——method+path 全路径归因
+ * 键；拒路径零审计）→ 返摘除 fn。
+ *
+ * /reload 换代门复检（03 §10.6）：disposer 摘旧 + 新代重走本受理序——
+ * bootPlugins 对每插件 fork.effect 兜底 `releaseFor`（compaction 同律双
+ * 保险）；撤授予位后旧路由不残留（换代重注册现判现拒）。
+ */
+import { adjudicateCapabilityDoor } from '../contracts/api.js';
+import { BaseError } from '../contracts/index.js';
+import { adjudicatePluginRoute } from './plugin-routes.js';
+/** 服务名常量（SERVICE_CATALOG 第三条 'sdk-routes'——fork 绑定落位单源） */
+export const SDK_ROUTES_SERVICE = 'sdk-routes';
+/** 高危面名（03 §4.6 v1 首批第二枚——门检/审计归因单源） */
+export const SDK_ROUTE_CAPABILITY = 'sdk.register-route';
+/**
+ * 受理器工厂（assembly 单真身构造位）。纯账面状态 + 零自持监听——面生命
+ * 周期归三入口，本件只做受理裁决与两时点解耦的账。
+ */
+export function createPluginRouteRegistry(options = {}) {
+    /** 在账路由（`${method} ${path}` 双键唯一——查重账与 core: 道注册键同形） */
+    const entries = new Map();
+    /** 活面引用（attachFace 后受理的晚注册承载位——face.stop 后 detachFace 清空） */
+    let liveFace;
+    /** 本插件在账数（数帽分帐输入——跨插件不共享） */
+    const countOf = (pluginId) => {
+        let n = 0;
+        for (const entry of entries.values())
+            if (entry.pluginId === pluginId)
+                n += 1;
+        return n;
+    };
+    /** 账面摘除（摘除 fn 与 releaseFor 共用——面在场连带摘挂 + 键释放可重注册） */
+    const remove = (key) => {
+        const entry = entries.get(key);
+        if (entry === undefined)
+            return;
+        entry.removeLive?.();
+        entries.delete(key);
+    };
+    return {
+        bindForPlugin({ pluginId, getOpens, inLoadWindow }) {
+            return {
+                register(descriptor) {
+                    // —— ① 装载窗（c-6/U4 同律窗先于门——受理窗装载期 only，回调窗延伸不适用）
+                    if (!inLoadWindow()) {
+                        throw new BaseError('PLUGIN_WINDOW_CLOSED', `注册动词 ctx.get("sdk-routes").register 在装载窗口外被拒（插件 ${pluginId}——路由注册只在 apply 执行期间合法，03 §2.2 第十三面）`);
+                    }
+                    // —— ② 门检前置先于查重（registerUiBackend 同律——未开门连查重都不可达）；
+                    // core: 官方件直开豁免（§4.6 判据：装配即用户意图），审计照记不豁免
+                    if (!pluginId.startsWith('core:')) {
+                        const verdict = adjudicateCapabilityDoor(getOpens(), SDK_ROUTE_CAPABILITY);
+                        if (!verdict.ok) {
+                            throw new BaseError('PLUGIN_CAPABILITY_DOOR_CLOSED', verdict.message);
+                        }
+                    }
+                    // —— ③ 纯函数裁决（词形/保留字 → 档位收窄 → 数帽 → 落面铸造——U5-1 件）
+                    const judged = adjudicatePluginRoute(pluginId, descriptor, { pluginRouteCount: countOf(pluginId) });
+                    if (!judged.ok) {
+                        throw new BaseError(judged.code, judged.message);
+                    }
+                    const full = judged.descriptor;
+                    const key = `${full.method} ${full.path}`;
+                    // —— ④ 查重：面在场走 face.register 既有 throw（同表同律字面复用）；
+                    // pending 态账内同形普通 Error（core: 道注册期消息形——零新码零重复执法）
+                    if (entries.has(key)) {
+                        if (liveFace !== undefined) {
+                            liveFace.register(full); // 既有 method+path 双键 throw——与 core: 道同表
+                        }
+                        throw new Error(`路由重复注册（method+path 双键唯一）：${key}——注册期 fail-loud`);
+                    }
+                    // —— ⑤ 受理入账（面在场附带挂载晚注册位——摘除 fn 双轨记录）
+                    let removeLive;
+                    if (liveFace !== undefined)
+                        removeLive = liveFace.register(full);
+                    entries.set(key, { pluginId, descriptor: full, ...(removeLive !== undefined ? { removeLive } : {}) });
+                    // —— ⑥ capability/used 恰一笔（受理成功后落；拒路径零审计；core: 照记）
+                    options.onCapabilityUsed?.({
+                        pluginId,
+                        capability: SDK_ROUTE_CAPABILITY,
+                        method: full.method,
+                        path: full.path,
+                    });
+                    // 摘除 fn（disposer 律 §2.6——/reload 换代回收腿的手动面；releaseFor 兜底双保险）
+                    return () => remove(key);
+                },
+            };
+        },
+        releaseFor(pluginId) {
+            for (const [key, entry] of [...entries]) {
+                if (entry.pluginId === pluginId)
+                    remove(key);
+            }
+        },
+        snapshot() {
+            return [...entries.values()].map((entry) => entry.descriptor);
+        },
+        attachFace(face) {
+            if (liveFace === face)
+                return; // 幂等保真（同面重复挂接 no-op）
+            liveFace = face;
+        },
+        detachFace() {
+            liveFace = undefined;
+        },
+    };
+}

package/dist/sdk/plugin-routes.js

@@ -0,0 +1,149 @@
+/* ---------------- 规约常量（03 §10.6 U5 定形注——数值钉死位） ---------------- */
+/** 插件道根段前缀（`/plugins/<id>/` 两段复合——前缀恒受理面施加、插件只申报 suffix） */
+export const PLUGIN_ROUTE_ROOT = '/plugins';
+/**
+ * 插件道请求体帽钳值（1MiB——可小不可大；**缺席即本值**：受理面填值后转发，
+ * 落面 descriptor 该位恒在场且 ≤1MiB，防面级缺省 10MiB 静默穿透）。
+ */
+export const PLUGIN_ROUTE_BODY_LIMIT_MAX_BYTES = 1024 * 1024;
+/** per-plugin 路由数帽（受理面计数、超帽拒 `SDK_ROUTE_LIMIT_REACHED`） */
+export const PLUGIN_ROUTE_LIMIT = 16;
+/** 插件道 open 档合法语义位子集（core: 道三值去 `auth-exchange`——插件不得自建换证端点） */
+export const PLUGIN_ROUTE_OPEN_PURPOSES = ['liveness', 'static-shell'];
+/* ---------------- 拼合单源（id → URL 段规约） ---------------- */
+/**
+ * 插件道路径拼合（单源——eliza 前缀默认施加判例采纳、rawPath 逃生门不设）：
+ * `/plugins/<encodeURIComponent(pluginId)><suffix>`。id 经 URL 段安全编码
+ * 承载特殊字符（'core:xxx' 冒号形 → 'core%3Axxx'——编码后不含 `/`，段边界
+ * 单源性由此保证）。
+ */
+export function pluginRoutePath(pluginId, suffix) {
+    return `${PLUGIN_ROUTE_ROOT}/${encodeURIComponent(pluginId)}${suffix}`;
+}
+/**
+ * 插件道路由受理裁决（纯函数零副作用——03 §10.6 受理序的纯函数段）：
+ *
+ * ① 词形/保留字校验（`SDK_ROUTE_PATH_RESERVED`——防御性回弹）：
+ *    suffix 须 `/` 开头（单独 `*` 全局形拒）；保留根段闭集 {`/v1/`, `/plugins/`}
+ *    撞入即拒（执法位本在 core: 道注册器，插件道经前缀施加律结构性框死于
+ *    `/plugins/<id>/` 之下——受理面此校验系纵深防御的回弹层）；段式正规形
+ *    （无空段 / `:name` 参数段字母数字下划线 / 通配 `*` 至多一枚且须尾段 /
+ *    字面段不含保留字符 `:` `*`）。
+ * ② 档位收窄裁决（`SDK_ROUTE_AUTH_FORBIDDEN` / `SDK_ROUTE_BODY_LIMIT`）：
+ *    鉴权档子集（self 拒、open 限 liveness·static-shell 两 purpose）；
+ *    bodyLimitBytes 非正整数或 >1MiB 拒（可小不可大）。
+ * ③ 数帽（`SDK_ROUTE_LIMIT_REACHED`）：本插件在册数达 16 拒。
+ * ④ 落面铸造：前缀施加 + loopbackOnly 恒 true + bodyLimitBytes 填值（缺席
+ *    即 1MiB）——descriptor 落面该位恒在场，面级缺省 10MiB 结构性不可达。
+ *
+ * 门检前置先于本函数（未开门连查重都不可达——registerUiBackend 同律）、
+ * capability/used 审计恰一笔（拒路径零审计）均归 U5-2 受理器编排。
+ */
+export function adjudicatePluginRoute(pluginId, descriptor, state) {
+    const { method, path: suffix, auth, handler } = descriptor;
+    // —— ① 词形/保留字（PATH_RESERVED——防御性回弹层）——
+    if (typeof pluginId !== 'string' || pluginId === '') {
+        return { ok: false, code: 'SDK_ROUTE_PATH_RESERVED', message: '插件 id 空缺——前缀拼合不可达' };
+    }
+    // 单独 `*`（全局吞一切）不以 / 开头，由起头判据一并拒；message 点名全局形归属
+    if (typeof suffix !== 'string' || !suffix.startsWith('/')) {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_PATH_RESERVED',
+            message: `插件道路由 path 须以 / 开头的 suffix（单独 * 全局形系 core: 道 SPA fallback 专属承载位、插件道不可达）：${method} ${suffix}`,
+        };
+    }
+    // 保留根段防御性回弹：前缀施加律下结构性不可撞，纵深防御仍显式拒
+    if (suffix === '/v1' ||
+        suffix.startsWith('/v1/') ||
+        suffix === PLUGIN_ROUTE_ROOT ||
+        suffix.startsWith(`${PLUGIN_ROUTE_ROOT}/`)) {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_PATH_RESERVED',
+            message: `插件道路由 path 撞保留根段闭集 {/v1/, /plugins/}——前缀施加律下 /plugins/<id>/ 域外结构性不可达（防御性回弹拒）：${method} ${suffix}`,
+        };
+    }
+    const segments = suffix.slice(1).split('/');
+    if (segments.some((seg) => seg === '')) {
+        return { ok: false, code: 'SDK_ROUTE_PATH_RESERVED', message: `插件道路由 path 空段非法：${method} ${suffix}` };
+    }
+    // 通配 `*`：至多一枚且须尾段（域内 catch-all——suffix 尾 * 映射 /plugins/<id>/*）
+    const starIndex = segments.indexOf('*');
+    if (starIndex !== -1 && (starIndex !== segments.length - 1 || segments.indexOf('*', starIndex + 1) !== -1)) {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_PATH_RESERVED',
+            message: `插件道路由 path 通配 * 至多一枚且须尾段：${method} ${suffix}`,
+        };
+    }
+    for (const seg of segments) {
+        if (seg.startsWith(':')) {
+            if (!/^[A-Za-z0-9_]+$/.test(seg.slice(1))) {
+                return {
+                    ok: false,
+                    code: 'SDK_ROUTE_PATH_RESERVED',
+                    message: `插件道路由参数名非法（字母数字下划线）：${method} ${suffix}`,
+                };
+            }
+        }
+        else if (seg !== '*' && /[:*]/.test(seg)) {
+            return {
+                ok: false,
+                code: 'SDK_ROUTE_PATH_RESERVED',
+                message: `插件道路由段含保留字符（: / *）：${method} ${suffix}`,
+            };
+        }
+    }
+    // —— ② 档位收窄（AUTH_FORBIDDEN / BODY_LIMIT）——
+    // 鉴权档子集：self 逃生档不对插件道开放（issue webhook HMAC 位系 host 装配独占）。
+    // 类型面已结构性排除 self（PluginRouteAuth 子集——tsc 即证无交集）；本判定
+    // 系 JS 调用方（jiti 装载零编译期）与类型漂移的防御性回弹，故显式拓宽比较
+    if (auth === 'self') {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_AUTH_FORBIDDEN',
+            message: '鉴权档 self 不对插件道开放（issue webhook HMAC 位系 host 装配独占逃生档）',
+        };
+    }
+    // open 档 purpose 射界子集：liveness·static-shell 两值（auth-exchange 不开——插件不得自建换证端点）
+    if (typeof auth === 'object' && auth !== null && auth.mode === 'open') {
+        const purpose = auth.purpose;
+        if (!PLUGIN_ROUTE_OPEN_PURPOSES.includes(purpose)) {
+            return {
+                ok: false,
+                code: 'SDK_ROUTE_AUTH_FORBIDDEN',
+                message: `open 档 purpose ${purpose} 不对插件道开放——合法语义位子集：${PLUGIN_ROUTE_OPEN_PURPOSES.join(' / ')}（auth-exchange 换证端点不开放）`,
+            };
+        }
+    }
+    // 体帽钳制：缺席即 1MiB 受理面填值；在场须正整数且 ≤1MiB（可小不可大）
+    const declared = descriptor.bodyLimitBytes;
+    if (declared !== undefined &&
+        (!Number.isSafeInteger(declared) || declared <= 0 || declared > PLUGIN_ROUTE_BODY_LIMIT_MAX_BYTES)) {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_BODY_LIMIT',
+            message: `bodyLimitBytes 须为正整数且 ≤${PLUGIN_ROUTE_BODY_LIMIT_MAX_BYTES}（1MiB，可小不可大；缺席即该帽值）：${String(declared)}`,
+        };
+    }
+    const bodyLimitBytes = declared ?? PLUGIN_ROUTE_BODY_LIMIT_MAX_BYTES;
+    // —— ③ 数帽（LIMIT_REACHED——per-plugin 在册数达帽拒）——
+    if (state.pluginRouteCount >= PLUGIN_ROUTE_LIMIT) {
+        return {
+            ok: false,
+            code: 'SDK_ROUTE_LIMIT_REACHED',
+            message: `插件道路由数帽 ${PLUGIN_ROUTE_LIMIT}已达（per-plugin 计数——摘除 fn 释放后可再注册）`,
+        };
+    }
+    // —— ④ 落面铸造（core: 道形——三处收窄全部落位）——
+    const full = {
+        method,
+        path: pluginRoutePath(pluginId, suffix),
+        auth,
+        loopbackOnly: true, // 恒 true：子集形无自选位（缺省 true 且不可自选 false 的结构性执法）
+        bodyLimitBytes, // 恒在场且 ≤1MiB：面级缺省 10MiB 结构性不可达
+        handler,
+    };
+    return { ok: true, descriptor: full };
+}