@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/load/config.js

@@ -0,0 +1,285 @@
+/**
+ * 1.1-S3 签名配置文件通道 → 1.5-S3 完整形态（car.config.ts + zod，D-22）→ 1.6-S3 jiti 载体（D-24）
+ *
+ * 口径：
+ *  - 载体（D-22 + D-24 修订）：发现序 **car.config.ts > car.config.json**（同目录两者并存 = ts 胜出，
+ *    json 忽略——禁静默合并）；显式 --config 按扩展名分派（.ts 走 TS 载体，其余 JSON 解析）；
+ *    TS 载体 = **jiti 自包含转译**（1.6-S3——零传递依赖 bundled 形态，第二个常规运行时依赖；
+ *    D-22「jiti 继续登记不引入」到期出清）：Node 22.19+ 加载 car.config.ts 不再依赖
+ *    --experimental-transform-types，非可擦除语法（enum 等 transform-only 形态）可用——
+ *    erasable-only 预检登记项随之出清（被取代）；插件加载的原生类型剥离纪律不动。
+ *    形态 = `export default {…}`（非对象/缺 default 显式报错）。
+ *  - **预热协议**：loadCarConfig 保持同步签名（doctor/resolveSigGate 等既有调用面不动）；
+ *    car.config.ts 须先经 warmCarConfig 异步预热入缓存（CLI 入口统一预热），未预热显式报错
+ *    （fail-visible，禁静默回退 json——「配置写了但不生效」的漂移面必须显式化）。
+ *  - 校验层 zod 化（D-11a ① 修订）：zod ^3 为首个常规运行时依赖（用户点名登记项）；
+ *    fail-visible 语义与 CAR-E-CONFIG 错误码保持，zod issues 渲染为 `路径 原因`（首个 issue）；
+ *    键位空间与 1.1/1.4 完全一致（sandbox.* / llm.* / mcp.*；mcp.servers 本迭代加 url/headers）。
+ *    未登记键 / 类型错 / 坏 JSON / 坏 TS 一律 CAR-E-CONFIG 显式拒绝（禁静默忽略）。
+ *  - 优先级（1.1 规划 §3 S3）：flag > env > 配置文件 > 缺省。env 已定义即为显式意见。
+ *    无配置文件 + 无 env 时行为与 1.0 完全一致（warn / 无信任根 / 不豁免）。
+ *  - 本模块只读配置与合并优先级；门禁判定在 sigGate/verifier。发现序：显式路径 > cwd。
+ *  - 代码求值面（D-22 登记）：car.config.ts 为本机文件信任边界（与插件同域；配置无签名机制）。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+export const CONFIG_FILENAME = 'car.config.json';
+export const CONFIG_TS_FILENAME = 'car.config.ts';
+// ==================== zod 校验层（1.5-S3 迁移；错误消息含 s31/s34 回归锚点） ====================
+// 叶子消息不含路径——渲染层统一拼 `${path} ${message}`（s31 锚点：'llm.maxTokens 必须为正整数'）
+const nonEmptyTrimmed = () => z.string({ invalid_type_error: '必须为非空字符串', required_error: '必须为非空字符串' })
+    .trim()
+    .refine(v => v.length > 0, { message: '必须为非空字符串' });
+const stringMap = () => z.record(z.string(), z.string({ invalid_type_error: '必须为字符串' }), { invalid_type_error: '必须为字符串映射', required_error: '必须为字符串映射' });
+const mcpServerSchema = z.object({
+    command: nonEmptyTrimmed().optional(),
+    url: nonEmptyTrimmed().refine(v => /^https?:\/\//.test(v), { message: '必须为 http(s) URL' }).optional(),
+    args: z.array(z.string({ invalid_type_error: '必须为字符串' }), { invalid_type_error: '必须为字符串数组' }).optional(),
+    env: stringMap().optional(),
+    headers: stringMap().optional(),
+}).strict().superRefine((obj, ctx) => {
+    const hasCommand = typeof obj.command === 'string' && !!obj.command;
+    const hasUrl = typeof obj.url === 'string' && !!obj.url;
+    if (hasCommand === hasUrl) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [], message: '需要 command（stdio）或 url（远程 Streamable HTTP）恰好其一（互斥）' });
+        return;
+    }
+    if (obj.args !== undefined && !hasCommand)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['args'], message: '仅 stdio 通道（command）适用' });
+    if (obj.env !== undefined && !hasCommand)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['env'], message: '仅 stdio 通道（command）适用' });
+    if (obj.headers !== undefined && !hasUrl)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['headers'], message: '仅远程通道（url）适用' });
+});
+const rawSchema = z.object({
+    sandbox: z.object({
+        unsigned: z.object({
+            allow: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+        }).strict().optional(),
+        sig: z.object({
+            enforce: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+            trustRoot: nonEmptyTrimmed().optional(),
+        }).strict().optional(),
+    }).strict().optional(),
+    llm: z.object({
+        baseUrl: nonEmptyTrimmed().optional(),
+        model: nonEmptyTrimmed().optional(),
+        adapterId: nonEmptyTrimmed().optional(),
+        maxTokens: z.number({ invalid_type_error: '必须为正整数', required_error: '必须为正整数' })
+            .refine(v => Number.isFinite(v) && Number.isInteger(v) && v > 0, { message: '必须为正整数' })
+            .optional(),
+        allowEnvFallback: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+    }).strict().optional(),
+    mcp: z.object({
+        servers: z.record(z.string(), mcpServerSchema, { invalid_type_error: '必须为对象（serverId → 启动规格）' }),
+    }).strict().optional(),
+}, { invalid_type_error: '配置顶层必须为 JSON 对象' }).strict();
+/** 未登记键提示（渲染层拼 path）——与系统设计键位空间同步 */
+const KEY_SPACES = '登记键位：sandbox.* / llm.* / mcp.servers.*';
+/** zod issue → CAR-E-CONFIG 渲染（首个 issue；unrecognized_keys 按键路径展开） */
+function renderIssue(error) {
+    const iss = error.issues[0];
+    if (iss.code === 'unrecognized_keys') {
+        const keys = iss.keys ?? [];
+        const keyPath = [...iss.path, keys[0] ?? '?'].join('.');
+        return iss.path.length
+            ? `CAR-E-CONFIG: 未知键 ${keyPath}（${KEY_SPACES}）`
+            : `CAR-E-CONFIG: 未知顶层键 "${keys[0] ?? '?'}"（${KEY_SPACES}）`;
+    }
+    const p = iss.path.join('.');
+    return p ? `CAR-E-CONFIG: ${p} ${iss.message}` : `CAR-E-CONFIG: ${iss.message}`;
+}
+/** zod 解析 → CarConfig（扁平渲染：sandbox 嵌套键拍平——mergeSignatureGate 消费形态不变） */
+function parseCarConfig(raw) {
+    const parsed = rawSchema.safeParse(raw);
+    if (!parsed.success)
+        return { config: {}, error: renderIssue(parsed.error) };
+    const d = parsed.data;
+    const out = {};
+    if (d.sandbox) {
+        const sb = {};
+        if (d.sandbox.unsigned?.allow !== undefined)
+            sb.unsignedAllow = d.sandbox.unsigned.allow;
+        if (d.sandbox.sig?.enforce !== undefined)
+            sb.sigEnforce = d.sandbox.sig.enforce;
+        if (d.sandbox.sig?.trustRoot !== undefined)
+            sb.sigTrustRoot = d.sandbox.sig.trustRoot;
+        out.sandbox = sb;
+    }
+    if (d.llm) {
+        const llm = {};
+        if (d.llm.baseUrl !== undefined)
+            llm.baseUrl = d.llm.baseUrl;
+        if (d.llm.model !== undefined)
+            llm.model = d.llm.model;
+        if (d.llm.adapterId !== undefined)
+            llm.adapterId = d.llm.adapterId;
+        if (d.llm.maxTokens !== undefined)
+            llm.maxTokens = d.llm.maxTokens;
+        if (d.llm.allowEnvFallback !== undefined)
+            llm.allowEnvFallback = d.llm.allowEnvFallback;
+        out.llm = llm;
+    }
+    if (d.mcp) {
+        const servers = {};
+        for (const [sid, sv] of Object.entries(d.mcp.servers)) {
+            const spec = {};
+            if (sv.command !== undefined)
+                spec.command = sv.command;
+            if (sv.url !== undefined)
+                spec.url = sv.url;
+            if (sv.args !== undefined)
+                spec.args = sv.args;
+            if (sv.env !== undefined)
+                spec.env = sv.env;
+            if (sv.headers !== undefined)
+                spec.headers = sv.headers;
+            servers[sid] = spec;
+        }
+        out.mcp = { servers };
+    }
+    return { config: out };
+}
+// ==================== 载体装载（JSON 同步 / TS 预热缓存） ====================
+/** car.config.ts 预热缓存（path → 装载结果；warmCarConfig 每次以新 epoch 查询串击穿模块缓存） */
+const tsCache = new Map();
+let tsEpoch = 0;
+/**
+ * 1.5-S3（D-22）→ 1.6-S3（D-24）：car.config.ts 载体预热。
+ * jiti 自包含转译（每 epoch 新实例 + moduleCache 关 = 击穿语义与 1.5 等价）——
+ * Node 22.19+ 无需 --experimental-transform-types；直接调用 loadCarConfig 的库方
+ * 在存在 car.config.ts 时须先 await 本函数（CLI 入口统一预热，协议不变）。
+ */
+export async function warmCarConfig(opts = {}) {
+    let path;
+    if (opts.explicitPath) {
+        if (!opts.explicitPath.endsWith('.ts'))
+            return; // JSON 显式路径走同步通道，无需预热
+        path = isAbsolute(opts.explicitPath) ? opts.explicitPath : join(opts.cwd ?? process.cwd(), opts.explicitPath);
+    }
+    else {
+        const candidate = join(opts.cwd ?? process.cwd(), CONFIG_TS_FILENAME);
+        if (!existsSync(candidate))
+            return; // cwd 发现序：无 ts 载体 = 无需预热（json 同步可读）
+        path = candidate;
+    }
+    tsEpoch++;
+    const result = await loadTsConfigFile(path, tsEpoch);
+    tsCache.set(path, result);
+}
+async function loadTsConfigFile(path, _epoch) {
+    try {
+        // D-24：jiti 转译（零传递依赖 bundled）；每 epoch 新实例 + moduleCache 关——击穿语义保持；
+        // interopDefault 显式关（jiti 缺省 true 会把无 default 模块的 exports 整体当 default 返回，
+        // 「缺 default export」fail-visible 校验即失效）
+        const { createJiti } = await import('jiti');
+        const jiti = createJiti(import.meta.url, { moduleCache: false, fsCache: false, interopDefault: false });
+        const mod = await jiti.import(path);
+        const raw = mod.default;
+        if (raw === undefined) {
+            return { path, config: {}, error: `CAR-E-CONFIG: ${path} 缺 default export（car.config.ts 形态 = export default {…}）` };
+        }
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+            return { path, config: {}, error: `CAR-E-CONFIG: ${path} default export 必须为对象（配置顶层）` };
+        }
+        const v = parseCarConfig(raw);
+        return v.error ? { path, config: {}, error: v.error } : { path, config: v.config };
+    }
+    catch (e) {
+        const err = e;
+        return { path, config: {}, error: `CAR-E-CONFIG: car.config.ts 载入失败（${err.message ?? String(e)}）——jiti 转译失败显式拒绝，不静默忽略` };
+    }
+}
+/** 加载配置：显式路径（必须存在，否则报错）或 cwd 发现（未发现 = 正常态返回空配置） */
+export function loadCarConfig(opts = {}) {
+    if (opts.explicitPath) {
+        const path = isAbsolute(opts.explicitPath) ? opts.explicitPath : join(opts.cwd ?? process.cwd(), opts.explicitPath);
+        if (path.endsWith('.ts')) {
+            const hit = tsCache.get(path);
+            if (hit)
+                return hit;
+            return { path, config: {}, error: `CAR-E-CONFIG: car.config.ts 未预热（CLI 入口自动 warmCarConfig；直接调用方须先 await warmCarConfig({ explicitPath })）` };
+        }
+        if (!existsSync(path)) {
+            return { path, config: {}, error: `CAR-E-CONFIG: 配置文件不存在：${path}（--config 显式指定的路径必须存在）` };
+        }
+        return loadJsonConfigFile(path);
+    }
+    // cwd 发现序（D-22）：car.config.ts > car.config.json（并存 = ts 胜出，json 忽略）
+    const tsPath = join(opts.cwd ?? process.cwd(), CONFIG_TS_FILENAME);
+    if (existsSync(tsPath)) {
+        const hit = tsCache.get(tsPath);
+        if (hit)
+            return hit;
+        return { path: tsPath, config: {}, error: `CAR-E-CONFIG: car.config.ts 未预热（CLI 入口自动 warmCarConfig；直接调用方须先 await warmCarConfig({ cwd })）` };
+    }
+    const jsonPath = join(opts.cwd ?? process.cwd(), CONFIG_FILENAME);
+    if (!existsSync(jsonPath))
+        return { config: {} };
+    return loadJsonConfigFile(jsonPath);
+}
+function loadJsonConfigFile(path) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (e) {
+        return { path, config: {}, error: `CAR-E-CONFIG: 配置文件解析失败（${e.message}）——坏 JSON 显式拒绝，不静默忽略` };
+    }
+    const v = parseCarConfig(raw);
+    return v.error ? { path, config: {}, error: v.error } : { path, config: v.config };
+}
+/**
+ * 1.4-S3（D-16）：模型接入配置合并（flag > env > 配置 > 缺省）。
+ * env 已定义为显式意见（压过配置），未定义落配置层——与 mergeSignatureGate 同纪律。
+ * 凭据不在此层（CR-05）：走 CredentialService（keychain → env OPENAI_API_KEY/ANTHROPIC_API_KEY/
+ * CAR_LLM_API_KEY，env fallback 需显式开启 = CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）。
+ */
+export function mergeLlmConfig(env, cfg, flags = {}) {
+    let baseUrl = cfg.llm?.baseUrl;
+    if (env.CAR_LLM_BASE_URL)
+        baseUrl = env.CAR_LLM_BASE_URL;
+    if (flags.baseUrl)
+        baseUrl = flags.baseUrl;
+    let model = cfg.llm?.model;
+    if (env.CAR_LLM_MODEL)
+        model = env.CAR_LLM_MODEL;
+    if (flags.model)
+        model = flags.model;
+    let adapterId = cfg.llm?.adapterId;
+    if (flags.adapterId)
+        adapterId = flags.adapterId;
+    let maxTokens = cfg.llm?.maxTokens;
+    if (flags.maxTokens !== undefined)
+        maxTokens = flags.maxTokens;
+    let allowEnvFallback = cfg.llm?.allowEnvFallback === true;
+    if (env.CAR_ALLOW_ENV_CREDENTIALS !== undefined)
+        allowEnvFallback = env.CAR_ALLOW_ENV_CREDENTIALS === '1';
+    return {
+        ...(baseUrl ? { baseUrl } : {}),
+        ...(model ? { model } : {}),
+        ...(adapterId ? { adapterId } : {}),
+        ...(maxTokens !== undefined ? { maxTokens } : {}),
+        allowEnvFallback,
+    };
+}
+/**
+ * 优先级合并（flag > env > 配置 > 缺省）：产出装载签名门选项。
+ * flagEnforce = CLI --sig-enforce；env 已定义即为显式意见（压过配置），未定义落配置层。
+ */
+export function mergeSignatureGate(env, cfg, flagEnforce) {
+    // cfg 为校验器产出的扁平形状（sandbox.{unsignedAllow,sigEnforce,sigTrustRoot}，JSON 嵌套键已拍平）
+    let mode = cfg.sandbox?.sigEnforce === true ? 'enforce' : 'warn';
+    if (env.CAR_SIG_ENFORCE !== undefined)
+        mode = env.CAR_SIG_ENFORCE === '1' ? 'enforce' : 'warn';
+    if (flagEnforce)
+        mode = 'enforce';
+    let trustRootPublicKey = cfg.sandbox?.sigTrustRoot;
+    if (env.CAR_TRUST_ROOT)
+        trustRootPublicKey = env.CAR_TRUST_ROOT;
+    let unsignedAllow = cfg.sandbox?.unsignedAllow === true;
+    if (env.CAR_UNSIGNED_ALLOW !== undefined)
+        unsignedAllow = env.CAR_UNSIGNED_ALLOW === '1';
+    return { mode, trustRootPublicKey: trustRootPublicKey || undefined, unsignedAllow };
+}

package/dist/load/loader.d.ts

@@ -0,0 +1,72 @@
+/**
+ * F10 · peer 版本约束校验（严格模式默认 + 显式豁免，经中间确认⑥）
+ * 冲突 = 加载期硬报错并输出冲突链；豁免需 manifest.peerPolicyOverride（reason 必填→审计留痕）
+ */
+export interface PeerViolation {
+    peer: string;
+    range: string;
+    installed: string | null;
+    optional: boolean;
+}
+/** 纯收集：仅计算违规项，不抛错（M6 加载报告用——冲突链需结构化定位而非只有异常消息） */
+export declare function computePeerViolations(manifest: Manifest, installed: Map<string, string>): PeerViolation[];
+export declare function validatePeers(manifest: Manifest, installed: Map<string, string>): {
+    exempted: boolean;
+    violations: PeerViolation[];
+};
+export interface Manifest {
+    name: string;
+    version: string;
+    peers?: Array<{
+        peer: string;
+        range: string;
+        optional?: boolean;
+    }>;
+    peerPolicyOverride?: {
+        relaxed: true;
+        reason: string;
+    };
+}
+export declare function parseManifest(raw: unknown, file?: string): Manifest;
+export interface ToolReg {
+    name: string;
+    run: (args: any) => Promise<unknown>;
+    /** 工具描述（进模型 function.description） */
+    description?: string;
+    /** 入参 JSON Schema（进模型 function.parameters） */
+    parameters?: unknown;
+    /** 副作用声明（缺省 write 收口——T-22 同款：未声明按最高约束） */
+    declaredSideEffect?: 'readonly' | 'write';
+}
+export interface CommandReg {
+    name: string;
+    run: (args: string[]) => Promise<void>;
+}
+export interface PluginApi {
+    registerTool(tool: ToolReg): void;
+    registerCommand(cmd: CommandReg): void;
+    getRegisteredTools(): ToolReg[];
+    /** 1.4-S2：插件设定 system prompt（session 级；last-wins；bindCore 时冲刷进宿主收集器，落 'system' 事件） */
+    setSystemPrompt(text: string): void;
+}
+interface HostBinding {
+    registerTool?(tool: ToolReg): void;
+    registerCommand?(cmd: CommandReg): void;
+    getRegisteredTools(): ToolReg[];
+    setSystemPrompt?(text: string): void;
+}
+export interface LoadedPlugin {
+    manifest: Manifest;
+    api: PluginApi;
+    bindCore(host: HostBinding): void;
+    invalidate(): void;
+    isInvalidated(): boolean;
+}
+/** 装配插件模块（免编译加载 + Stub 占位 + invalidate 语义） */
+export declare function mountPlugin(spec: {
+    file: string;
+    manifest: unknown;
+    /** reload 版本号：每次 +1 变更 import 查询串击穿 ESM 缓存 */
+    reloadEpoch?: number;
+}): Promise<LoadedPlugin>;
+export {};

package/dist/load/loader.js

@@ -0,0 +1,162 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * F6 · 插件装配层：manifest 校验 + 免编译加载（缓存击穿热重载）+ Stub 占位 + invalidate
+ *
+ * 口径：
+ *  - 载体：jiti 实装受阻（沙箱 npm），以 Node --experimental-transform-types + 动态 import
+ *    查询串缓存击空承载（POC-2 同口径）；被测不变量与载体无关
+ *  - Stub 占位（Pi 范式，CAR 自研层）：**注册类动作始终可用（收集待注册项）**，
+ *    「依赖宿主绑定的能力查询」在 bindCore 前一调用即抛错——用启动期显式失败换运行期时序正确
+ *  - invalidate：unload/reload 后旧句柄访问显式报错（CAR-INVALIDATED）
+ *  - manifest：name 必填、version 精确 semver（禁区间）；peer 校验挂点预留（O7，M2 启用）
+ */
+import { pathToFileURL } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { checkErasableOnly } from '../ptc/erasable.js';
+/** 简易 semver 区间求解（M2 S5：仅支持 ^x.y.z / x.y.z 两种形态；完整区间求解 M3 扩展） */
+function satisfiesRange(version, range) {
+    if (range === version)
+        return true;
+    const m = /^\^(\d+)\.(\d+)\.(\d+)$/.exec(range);
+    if (!m)
+        return false;
+    const [M, mnr, P] = version.split('.').map(Number);
+    // npm caret 语义：左起第一个非零位锁定（^1.2.3→>=1.2.3 <2；^0.2.3→>=0.2.3 <0.3；^0.0.3→==0.0.3）
+    if (M !== Number(m[1]))
+        return false;
+    if (M > 0) {
+        if (mnr !== Number(m[2]))
+            return mnr > Number(m[2]);
+        return P >= Number(m[3]);
+    }
+    if (mnr !== Number(m[2]))
+        return false; // ^0.x：minor 锁定
+    return P >= Number(m[3]);
+}
+/** 纯收集：仅计算违规项，不抛错（M6 加载报告用——冲突链需结构化定位而非只有异常消息） */
+export function computePeerViolations(manifest, installed) {
+    const violations = [];
+    for (const p of manifest.peers ?? []) {
+        const v = installed.get(p.peer);
+        if (v === undefined) {
+            if (!p.optional)
+                violations.push({ peer: p.peer, range: p.range, installed: null, optional: false });
+            continue;
+        }
+        if (!satisfiesRange(v, p.range))
+            violations.push({ peer: p.peer, range: p.range, installed: v, optional: !!p.optional });
+    }
+    return violations;
+}
+export function validatePeers(manifest, installed) {
+    const violations = computePeerViolations(manifest, installed);
+    const hard = violations.filter(v => !v.optional);
+    if (!hard.length)
+        return { exempted: false, violations };
+    if (manifest.peerPolicyOverride?.relaxed) {
+        // 显式豁免：放宽生效，调用方负责将 manifest.peerPolicy='exempt' 写入审计（留痕）
+        return { exempted: true, violations };
+    }
+    // 严格模式默认：冲突链硬报错（文件/依赖路径/区间/实际版本）
+    const chainStr = hard.map(v => `${v.peer}@${v.range} required but ${v.installed ?? '<missing>'} installed`).join('; ');
+    throw new Error(`CAR-E-PEER: peer dependency conflict for "${manifest.name}" — ${chainStr}（放宽需 manifest.peerPolicyOverride 显式声明 + reason，审计留痕）`);
+}
+const SEMVER_EXACT = /^\d+\.\d+\.\d+$/;
+const chain = (file, detail) => `CAR-E-MANIFEST: ${detail} (conflict chain: ${file})`;
+export function parseManifest(raw, file = '<manifest>') {
+    const m = raw;
+    if (!m || typeof m !== 'object')
+        throw new Error(chain(file, 'manifest must be an object'));
+    if (!m.name || typeof m.name !== 'string')
+        throw new Error(chain(file, 'field "name" is required and must be a string'));
+    if (!m.version || !SEMVER_EXACT.test(m.version)) {
+        throw new Error(chain(file, `field "version" must be exact semver (x.y.z), got "${m.version}"（版本区间仅用于 peer 校验）`));
+    }
+    if (m.peerPolicyOverride && !m.peerPolicyOverride.reason) {
+        throw new Error(chain(file, 'field "peerPolicyOverride.reason" is required when豁免声明（审计留痕）'));
+    }
+    return m;
+}
+class ApiImpl {
+    #host;
+    #pendingTools = [];
+    #pendingCommands = [];
+    #pendingSystemPrompt = null;
+    registerTool(tool) {
+        if (this.#host?.registerTool) {
+            this.#host.registerTool(tool);
+            return;
+        }
+        this.#pendingTools.push(tool); // 注册类动作始终可用：Stub 期收集，bind 后冲刷
+    }
+    registerCommand(cmd) {
+        if (this.#host?.registerCommand) {
+            this.#host.registerCommand(cmd);
+            return;
+        }
+        this.#pendingCommands.push(cmd);
+    }
+    setSystemPrompt(text) {
+        if (this.#host?.setSystemPrompt) {
+            this.#host.setSystemPrompt(text);
+            return;
+        }
+        this.#pendingSystemPrompt = text; // last-wins：多次设定取最后一次
+    }
+    getRegisteredTools() {
+        // 依赖宿主绑定的能力查询：bindCore 前一调用即抛错（Stub 显式失败）
+        if (!this.#host)
+            throw new Error('CAR-STUB: "getRegisteredTools" called before bindCore（启动期显式失败换运行期时序正确）');
+        return this.#host.getRegisteredTools();
+    }
+    bindHost(host) {
+        this.#host = host;
+        for (const t of this.#pendingTools)
+            host.registerTool?.(t);
+        for (const c of this.#pendingCommands)
+            host.registerCommand?.(c);
+        if (this.#pendingSystemPrompt !== null)
+            host.setSystemPrompt?.(this.#pendingSystemPrompt);
+        this.#pendingTools = [];
+        this.#pendingCommands = [];
+        this.#pendingSystemPrompt = null;
+    }
+}
+/** 装配插件模块（免编译加载 + Stub 占位 + invalidate 语义） */
+export async function mountPlugin(spec) {
+    const manifest = parseManifest(spec.manifest, spec.file);
+    const epoch = spec.reloadEpoch ?? 0;
+    // erasable-only 双挂点之二：loader 提交链（挂点一在 run_code 入口——单一事实源 checkErasableOnly）
+    const era = checkErasableOnly(readFileSync(spec.file, 'utf-8'));
+    if (!era.ok)
+        throw new Error(`CAR-E-PTC: ${era.violation} (file: ${spec.file})`);
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(spec.file).href + (epoch ? `?epoch=${epoch}` : ''))));
+    if (typeof mod.default !== 'function') {
+        throw new Error(chain(spec.file, 'plugin module must default-export a factory (api) => void'));
+    }
+    let alive = true;
+    const apiImpl = new ApiImpl();
+    const api = new Proxy(apiImpl, {
+        get(target, prop) {
+            if (!alive)
+                throw new Error(`CAR-INVALIDATED: "${prop}" on stale plugin context（旧上下文已失效，请重新加载）`);
+            const v = target[prop];
+            return typeof v === 'function' ? v.bind(target) : v;
+        },
+    });
+    mod.default(api);
+    return {
+        manifest,
+        api,
+        bindCore(host) { apiImpl.bindHost(host); },
+        invalidate() { alive = false; },
+        isInvalidated() { return !alive; },
+    };
+}

package/dist/load/registry.d.ts

@@ -0,0 +1,44 @@
+export interface RegistryEntry {
+    url: string;
+    priority: number; /** 签名物承载方式（T-5 定稿①：不参与信任分级，验签义务恒在 verifier） */
+    signed: boolean;
+}
+export interface RegistryConfig {
+    registries: RegistryEntry[];
+    /** 公共 npm 兜底（缺省必须显式声明——企业内网 false 为试点准入判据，T-5 定稿③） */
+    allowNpmFallback: boolean;
+    /** 离线模式：全部拒绝（显式错误） */
+    offline: boolean;
+}
+export interface PackageSpec {
+    name: string;
+    version: string; /** 显式源绑定（manifest registry 字段）——校验级失败硬失败不换源 */
+    pinnedRegistry?: string;
+}
+export type ResolutionSource = 'registry' | 'npm-fallback' | 'rejected';
+export interface Resolution {
+    source: ResolutionSource;
+    url?: string;
+    /** 判定摘要（审计落盘 payload；含拒绝原因/解析路径） */
+    detail: string;
+    /** 解析决策指纹（可落审计哈希链） */
+    decisionId: string;
+}
+/**
+ * 单源失败排除记录（T-5 定稿②）：reason 类型层仅允许 'network'——
+ * 「校验级失败换源」在本签名上不可表达（校验失败由调用方硬拒，不经本层换源）。
+ */
+export type ExcludedSource = {
+    url: string;
+    reason: 'network';
+};
+export declare function resolvePackage(spec: PackageSpec, config: RegistryConfig, audit?: (detail: Record<string, unknown>) => void, opts?: {
+    exclude?: ExcludedSource[];
+}): Resolution;
+/** 只读预览（T-5 定稿②新增）：返回按优先级的候选链（不含 pinned 语义，供装载面展示与演练） */
+export declare function resolveCandidateChain(config: RegistryConfig): {
+    chain: string[];
+    fallback: boolean;
+};
+/** 白名单校验（插件安装面调用：来源不在清单 = 拒绝并审计） */
+export declare function isWhitelisted(url: string, config: RegistryConfig): boolean;

package/dist/load/registry.js

@@ -0,0 +1,58 @@
+/**
+ * T-3/T-4 · registry 对接（M3-S13 落位 + M4-S17 T-5 终局对齐增补）
+ *
+ * 口径（M3部署设计增补 §3 + M3安全设计增补 T-4 + 决议⑦ + M4安全增补registry对齐 定稿）：
+ *  - **registries 清单即白名单本身**：白名单外默认拒绝 + 审计落盘（不做静默 fallback）；
+ *  - resolution 四级顺序：①显式源绑定（校验级失败**硬失败不换源**——换源重试已拒内容 = 降级攻击面）
+ *    → ②白名单 priority 升序（网络级失败可按 priority 继续——exclude 通道，类型上仅允许 reason='network'）
+ *    → ③公共 npm 兜底（缺省 false——**候选耗尽**或白名单为空时生效，企业内网安全默认）
+ *    → ④全不可用 = 离线拒绝（显式错误，非静默）；
+ *  - **signed 字段语义（T-5 定稿①）**：签名物承载方式（true=源直供 / false=镜像透传），**永不产生免验/降档/直信**——验签义务恒在 verifier 层（ADR-003）；
+ *  - 本模块纯判定（零网络 I/O），CI 可全量测试。
+ */
+import { createHash } from 'node:crypto';
+export function resolvePackage(spec, config, audit, opts = {}) {
+    const finish = (r) => {
+        const decisionId = 'RD-' + createHash('sha256').update(JSON.stringify({ spec, r })).digest('hex').slice(0, 16);
+        audit?.({ kind: 'registry-resolution', spec: spec.name, ...r, decisionId });
+        return { ...r, decisionId };
+    };
+    // ④ 离线：全拒（最高优先级——离线声明不可被任何源覆盖）
+    if (config.offline)
+        return finish({ source: 'rejected', detail: 'offline mode: all sources rejected（显式拒绝，非静默）' });
+    const excluded = new Set((opts.exclude ?? []).map(e => e.url));
+    // ① 显式源绑定：校验级失败硬失败不换源（pinned 不在白名单）；
+    //   pinned 命中但被 exclude（网络失败）→ 语义同「按 priority 继续」（T-5 定稿②网络路径）
+    if (spec.pinnedRegistry) {
+        const pinned = config.registries.find(r => r.url === spec.pinnedRegistry);
+        if (!pinned)
+            return finish({ source: 'rejected', detail: `pinned registry "${spec.pinnedRegistry}" not in whitelist——显式绑定不在白名单，硬失败不换源（fail-closed）` });
+        if (!excluded.has(pinned.url)) {
+            return finish({ source: 'registry', url: pinned.url, detail: `pinned to ${pinned.url}（priority=${pinned.priority}）` });
+        }
+        // pinned 网络失败：落审计后按 priority 继续剩余白名单（不含 pinned）
+    }
+    // ② 白名单 priority 升序（排除网络失败源）
+    const sorted = [...config.registries].sort((a, b) => a.priority - b.priority).filter(r => !excluded.has(r.url));
+    if (sorted.length) {
+        const first = sorted[0];
+        return finish({ source: 'registry', url: first.url, detail: `whitelist priority order → ${first.url}（candidates=${sorted.length}${excluded.size ? `, excluded=${excluded.size}` : ''}）` });
+    }
+    // ③ 公共 npm 兜底（**候选耗尽**或白名单为空时生效——T-5 定稿②③修正语义）
+    if (config.allowNpmFallback) {
+        const why = config.registries.length ? 'candidates exhausted（网络级失败耗尽）' : 'whitelist empty';
+        return finish({ source: 'npm-fallback', url: 'https://registry.npmjs.org', detail: `${why} → npm fallback（显式开启；兜底命中包强制过 verifier 不降级）` });
+    }
+    return finish({ source: 'rejected', detail: config.registries.length
+            ? 'candidates exhausted and npm fallback disabled——候选耗尽且兜底关闭（fail-closed）'
+            : 'no whitelist entries and npm fallback disabled——白名单为空且兜底关闭（企业内网安全默认）' });
+}
+/** 只读预览（T-5 定稿②新增）：返回按优先级的候选链（不含 pinned 语义，供装载面展示与演练） */
+export function resolveCandidateChain(config) {
+    const chain = [...config.registries].sort((a, b) => a.priority - b.priority).map(r => r.url);
+    return { chain, fallback: config.allowNpmFallback };
+}
+/** 白名单校验（插件安装面调用：来源不在清单 = 拒绝并审计） */
+export function isWhitelisted(url, config) {
+    return !config.offline && config.registries.some(r => r.url === url);
+}