@lqc123qwe/car-runtime 1.8.0 → 1.10.0

package/dist/load/report.d.ts

@@ -0,0 +1,98 @@
+import { type Manifest, type LoadedPlugin } from './loader.ts';
+import { type SignatureGateOptions } from './sigGate.ts';
+export type LoadStage = 'discover' | 'verify' | 'parse' | 'validate' | 'topo' | 'register';
+export type StageStatus = 'PASS' | 'FAIL' | 'SKIPPED';
+/** 冲突链定位：文件 / 依赖路径 / 区间 / 实际版本（§3.2.M6.3 stages[].conflicts） */
+export interface PeerConflictChain {
+    /** 违规声明所在插件文件 */
+    file: string;
+    peer: string;
+    range: string;
+    installed: string | null;
+    /** 依赖路径（声明来源，如 manifest.peers） */
+    path: string;
+}
+export interface LoadReportVO {
+    installId: string;
+    startedTime: string;
+    durationMs: number;
+    stages: Array<{
+        stage: LoadStage;
+        status: StageStatus;
+        /** validate FAIL 时的 peer 冲突链 */
+        conflicts?: PeerConflictChain[];
+        /** 规格外扩展：FAIL 错误定位（文件 + 原因；冲突类失败用 conflicts，其余用 error） */
+        error?: {
+            file: string;
+            reason: string;
+        };
+    }>;
+    warnings: string[];
+}
+/** 装配计划（renderLoadReport 的第一参；由 loadPlugins 在各阶段推进中冻结） */
+export interface LoadPlan {
+    installId: string;
+    source: string;
+    /** ISO 8601 起始时间（进入报告） */
+    startedTime: string;
+    /** 内部计时基准（epoch ms，用于 durationMs） */
+    startedAtMs: number;
+    /** discover 产物：插件文件绝对路径（拓扑序待 topo 阶段确定） */
+    files: string[];
+    reloadEpoch?: number;
+    /** 装配期告警（git 直载 / peer 豁免等，E-03 语义） */
+    warnings: string[];
+}
+/** 阶段执行中间结果（内部类型，冻结前由各阶段填充） */
+export interface LoadStageResult {
+    stage: LoadStage;
+    status: StageStatus;
+    conflicts?: PeerConflictChain[];
+    error?: {
+        file: string;
+        reason: string;
+    };
+}
+/** 生成安装 ID（进程内单调 + 时间戳，可读可留审计） */
+export declare function newInstallId(now?: number): string;
+export declare function renderLoadReport(plan: LoadPlan, stageReports: LoadStageResult[]): LoadReportVO;
+export interface DiscoveredEntry {
+    file: string;
+    manifestRaw: unknown;
+}
+export interface LoadPluginsOptions {
+    /** 插件目录（扫描 *.ts）或单插件文件路径 */
+    source: string;
+    /** 热重载版本号：>0 时以 ?epoch=N 查询串击穿 ESM 缓存 */
+    reloadEpoch?: number;
+    /** 批外已安装插件版本（peer 校验的 installed 基线；缺省仅用本批次内 manifest） */
+    installedVersions?: Map<string, string>;
+    /** 显式声明 git 直载来源（如经 git URL 拉取后未走 registry 安装）——补充扫描 .git 探测 */
+    gitDirect?: boolean;
+    /** 装载签名门（M5-S28）：缺省 warn 模式全量启用——缺签横幅放行，enforce 显式切入 */
+    signature?: SignatureGateOptions;
+}
+export interface LoadPluginsResult {
+    report: LoadReportVO;
+    /** register 成功装配的插件（拓扑序；FAIL 短路时为已装配前缀或空） */
+    plugins: LoadedPlugin[];
+    /** 拓扑序 manifest（供 CLI/测试断言装配顺序） */
+    order: Manifest[];
+}
+/** 六阶段装配：discover → verify → parse → validate → topo → register（任一 FAIL 短路，后续 SKIPPED） */
+export declare function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPluginsResult>;
+/** 报告 → stdout 行（CLI 打印用；PASS/FAIL + 定位 + 耗时） */
+export declare function formatLoadReport(report: LoadReportVO): string[];
+/** 热重载会话：持有 epoch 与实例注册表，reload() 重走五阶段并 invalidate 旧实例 */
+export declare class ReloadManager {
+    #private;
+    get epoch(): number;
+    get instances(): readonly LoadedPlugin[];
+    get history(): readonly LoadReportVO[];
+    /**
+     * SQ-05 时序：epoch+1 击穿缓存 → invalidate 旧实例（旧 ctx 后续访问抛 CAR-INVALIDATED）
+     * → 重走 discover→register → 五阶段报告。任一阶段 FAIL 即返回 FAIL 报告（旧实例已失效，
+     * 不做静默回退——加载期显式失败红线）。
+     */
+    reload(source: string, opts?: Omit<LoadPluginsOptions, 'source' | 'reloadEpoch'>): Promise<LoadPluginsResult>;
+}

package/dist/load/report.js

@@ -0,0 +1,301 @@
+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;
+};
+/**
+ * M6 · 加载报告与装配编排（《系统设计》§3.2.M6）
+ *
+ * 口径：
+ *  - 六阶段流水线：discover → verify → parse → validate → topo → register，任一阶段 FAIL 短路
+ *    后续阶段（status=SKIPPED），FAIL 必附错误定位（文件 + 原因，冲突链进 conflicts）。
+ *    verify 为 M5-S28 加法演进（2026-09-26）：装载前签名门（ADR-003 / DEC-1 ②）——必须先于
+ *    parse 的 import()，模块执行前拦截（否则恶意代码已运行，验签失去供应链意义）
+ *  - LoadReportVO 字段名逐字对齐 §3.2.M6.3（installId/startedTime/durationMs/stages/warnings）；
+ *    `error` 为规格外扩展字段（非冲突类失败——如 manifest 语法错——也需要文件+原因定位，BD-03）
+ *  - git 直载（工作树内含 .git 即视为未经 registry 安装的直载来源）产生 CAR-W-GIT-DIRECT 告警（E-03 语义）
+ *  - 热重载（SQ-05）：epoch+1 击穿缓存 → invalidate 旧实例（旧 ctx 后续访问经 Proxy 抛
+ *    CAR-INVALIDATED）→ 重走 discover→register，产出六阶段加载报告
+ */
+import { readdirSync, existsSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseManifest, validatePeers, computePeerViolations, mountPlugin, } from './loader.js';
+import { verifyPluginFile } from './sigGate.js';
+// ==================== renderLoadReport（报告冻结：plan + 阶段执行结果 → VO） ====================
+let installSeq = 0;
+/** 生成安装 ID（进程内单调 + 时间戳，可读可留审计） */
+export function newInstallId(now = Date.now()) {
+    installSeq += 1;
+    return `car-install-${now.toString(36)}-${installSeq.toString(36).padStart(3, '0')}`;
+}
+export function renderLoadReport(plan, stageReports) {
+    return {
+        installId: plan.installId,
+        startedTime: plan.startedTime,
+        durationMs: Date.now() - plan.startedAtMs,
+        stages: stageReports.map(s => ({
+            stage: s.stage,
+            status: s.status,
+            ...(s.conflicts ? { conflicts: s.conflicts } : {}),
+            ...(s.error ? { error: s.error } : {}),
+        })),
+        warnings: [...plan.warnings],
+    };
+}
+const GIT_URL_RE = /^(?:git\+|git@|ssh:\/\/git@)/;
+const CAR_W_GIT = 'CAR-W-GIT-DIRECT';
+const CAR_E = (stage, msg) => `CAR-E-${stage.toUpperCase()}: ${msg}`;
+const STAGE_ORDER = ['discover', 'verify', 'parse', 'validate', 'topo', 'register'];
+/** 六阶段装配：discover → verify → parse → validate → topo → register（任一 FAIL 短路，后续 SKIPPED） */
+export async function loadPlugins(opts) {
+    const startedAtMs = Date.now();
+    const startedTime = new Date(startedAtMs).toISOString();
+    const epoch = opts.reloadEpoch ?? 0;
+    const warnings = [];
+    const stages = [];
+    let files = [];
+    let ordered = [];
+    // 短路收口：为尚未执行的阶段补 SKIPPED，冻结 plan → LoadReportVO
+    const finish = (ps) => {
+        const complete = [...stages];
+        for (const s of STAGE_ORDER) {
+            if (!complete.some(d => d.stage === s))
+                complete.push({ stage: s, status: 'SKIPPED' });
+        }
+        const plan = {
+            installId: newInstallId(startedAtMs),
+            source: opts.source,
+            startedTime,
+            startedAtMs,
+            files,
+            reloadEpoch: epoch,
+            warnings,
+        };
+        return { report: renderLoadReport(plan, complete), plugins: ps, order: ordered };
+    };
+    // ===== 阶段 1：discover（扫描插件目录 *.ts；git 直载来源产生告警） =====
+    if (opts.gitDirect || GIT_URL_RE.test(opts.source)) {
+        // git 直载告警先于扫描：直载 URL 本地不存在也能在 FAIL 报告中携带来源告警（E-03）
+        warnings.push(`${CAR_W_GIT}: 插件来源为 git 直载（${opts.source}）——未经 registry 验签，建议改用 registry 安装（E-03）`);
+    }
+    try {
+        files = discoverFiles(opts.source);
+        if (existsSync(opts.source) && statSync(opts.source).isDirectory() && existsSync(join(opts.source, '.git'))) {
+            warnings.push(`${CAR_W_GIT}: 插件目录位于 git 工作树（${opts.source}）——未经 registry 验签的直载来源（E-03）`);
+        }
+        if (!files.length) {
+            stages.push({ stage: 'discover', status: 'FAIL', error: { file: opts.source, reason: CAR_E('discover', `no *.ts plugin files found under "${opts.source}"`) } });
+            return finish([]);
+        }
+        stages.push({ stage: 'discover', status: 'PASS' });
+    }
+    catch (e) {
+        stages.push({ stage: 'discover', status: 'FAIL', error: { file: opts.source, reason: `${e.message}` } });
+        return finish([]);
+    }
+    // ===== 阶段 2：verify（装载前签名门——先于 parse 的 import()，模块执行前拦截；ADR-003 / DEC-1 ②） =====
+    const sig = opts.signature ?? {};
+    const sigOnCount = sig.onCount;
+    for (const file of files) {
+        const g = verifyPluginFile(file, sig);
+        if (!g.allowed) {
+            sigOnCount?.('car_load_total', { result: 'failed' });
+            stages.push({ stage: 'verify', status: 'FAIL', error: { file, reason: g.error ?? 'CAR-E-SIG: rejected by signature gate' } });
+            return finish([]);
+        }
+        if (g.warning)
+            warnings.push(g.warning);
+    }
+    stages.push({ stage: 'verify', status: 'PASS' });
+    // ===== 阶段 3：parse（parseManifest；manifest 取模块命名导出，缺失则按文件名合成） =====
+    const entries = [];
+    for (const file of files) {
+        try {
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href + (epoch ? `?epoch=${epoch}` : ''))));
+            entries.push({ file, manifestRaw: mod.manifest ?? { name: basename(file).replace(/\.ts$/, ''), version: '0.0.1' } });
+        }
+        catch (e) {
+            stages.push({ stage: 'parse', status: 'FAIL', error: { file, reason: `CAR-E-PARSE: module import failed — ${e.message}` } });
+            return finish([]);
+        }
+    }
+    const parsed = [];
+    for (const { file, manifestRaw } of entries) {
+        try {
+            parsed.push({ file, manifest: parseManifest(manifestRaw, file) });
+        }
+        catch (e) {
+            stages.push({ stage: 'parse', status: 'FAIL', error: { file, reason: e.message } });
+            return finish([]);
+        }
+    }
+    const manifests = parsed.map(p => p.manifest);
+    stages.push({ stage: 'parse', status: 'PASS' });
+    // ===== 阶段 4：validate（peer 冲突链；豁免需 reason → 告警留痕） =====
+    const installed = opts.installedVersions ?? new Map();
+    for (const m of manifests)
+        installed.set(m.name, m.version);
+    const conflicts = [];
+    const exemptDetail = [];
+    let exemptedAny = false;
+    for (const { file, manifest: m } of parsed) {
+        try {
+            const r = validatePeers(m, installed);
+            if (r.exempted) {
+                // 豁免生效：不进 FAIL 冲突链，仅告警留痕（reason 已在 manifest 声明）
+                exemptedAny = true;
+                for (const v of r.violations.filter(v => !v.optional)) {
+                    exemptDetail.push(`${file}: peer ${v.peer}@${v.range} vs ${v.installed ?? '<missing>'}`);
+                }
+            }
+        }
+        catch {
+            // 严格模式硬冲突：不中止校验其余插件，收集全量冲突链后统一 FAIL（BD-03 定位口径）
+            for (const v of computePeerViolations(m, installed).filter(v => !v.optional))
+                conflicts.push(toChain(file, v));
+        }
+    }
+    if (conflicts.length) {
+        stages.push({ stage: 'validate', status: 'FAIL', conflicts });
+        return finish([]);
+    }
+    if (exemptedAny)
+        warnings.push(`CAR-W-PEER-EXEMPT: peer 冲突经 manifest.peerPolicyOverride 显式豁免（${exemptDetail.join('; ')}）——reason 已声明，审计留痕`);
+    stages.push({ stage: 'validate', status: 'PASS' });
+    // ===== 阶段 5：topo（peer 依赖边 → Kahn 分层拓扑排序；环 = 显式报错） =====
+    try {
+        ordered = topoSort(manifests);
+    }
+    catch (e) {
+        stages.push({ stage: 'topo', status: 'FAIL', error: { file: opts.source, reason: e.message } });
+        return finish([]);
+    }
+    stages.push({ stage: 'topo', status: 'PASS' });
+    // ===== 阶段 6：register（mountPlugin 按拓扑序装配；重名 = 显式冲突 + 冲突链定位） =====
+    const plugins = [];
+    const seenNames = new Set();
+    for (const m of ordered) {
+        const file = parsed.find(p => p.manifest.name === m.name)?.file ?? '';
+        if (seenNames.has(m.name)) {
+            // M6-BUG-1：重名冲突链 = 全部同名文件路径（BD-03：文件级定位，不再误导为依赖环）
+            const dupFiles = parsed.filter(p => p.manifest.name === m.name).map(p => p.file);
+            stages.push({ stage: 'register', status: 'FAIL', error: { file, reason: `CAR-E-DUP: plugin "${m.name}" registered more than once (duplicate registration is blocked) (conflict chain: ${dupFiles.join(', ')})` } });
+            return finish(plugins);
+        }
+        seenNames.add(m.name);
+        try {
+            plugins.push(await mountPlugin({ file, manifest: m, reloadEpoch: epoch }));
+            // S17 采集面：load_total(ok) 逐插件计数（unsigned 占比分母；零内容 labels）
+            sigOnCount?.('car_load_total', { result: 'ok' });
+        }
+        catch (e) {
+            stages.push({ stage: 'register', status: 'FAIL', error: { file, reason: e.message } });
+            return finish(plugins);
+        }
+    }
+    stages.push({ stage: 'register', status: 'PASS' });
+    return finish(plugins);
+}
+function toChain(declaringFile, v) {
+    return { file: declaringFile, peer: v.peer, range: v.range, installed: v.installed, path: 'manifest.peers' };
+}
+/** discover：目录扫描 *.ts（排除 .d.ts / .spec.ts）；单文件直载原样返回 */
+function discoverFiles(source) {
+    if (!existsSync(source)) {
+        throw new Error(CAR_E('discover', `source not found: "${source}"`));
+    }
+    if (statSync(source).isFile())
+        return [source];
+    return readdirSync(source)
+        .filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts') && !f.endsWith('.spec.ts'))
+        .sort()
+        .map(f => join(source, f));
+}
+/**
+ * topo：Kahn 分层——边 = 非可选 peer 指向批次内另一插件；环 = CAR-E-DEPCYCLE。
+ * 重名安全（M6-BUG-1）：放置判定按 manifest 逐个推进 + pushedNames 记名级放置——
+ * 重名 manifest 在首个同名放置后即可全部放置，不再因 name 键碰撞被误判为依赖环；
+ * 重名的显式冲突由 register 阶段 CAR-E-DUP 报出（BD-03：不误导定位到 topo）。
+ */
+function topoSort(manifests) {
+    const names = new Set(manifests.map(m => m.name));
+    const depsOf = new Map();
+    for (const m of manifests) {
+        const deps = depsOf.get(m.name) ?? new Set();
+        for (const p of m.peers ?? []) {
+            if (!p.optional && names.has(p.peer) && p.peer !== m.name)
+                deps.add(p.peer);
+        }
+        depsOf.set(m.name, deps);
+    }
+    const ordered = [];
+    const pushed = new Set();
+    const pushedNames = new Set();
+    let progressed = true;
+    while (ordered.length < manifests.length && progressed) {
+        progressed = false;
+        for (const m of manifests) {
+            if (pushed.has(m))
+                continue;
+            // 就绪条件：自身名已放置（重名后续项）或全部 peer 依赖已放置
+            if (pushedNames.has(m.name) || [...depsOf.get(m.name)].every(d => pushedNames.has(d))) {
+                ordered.push(m);
+                pushed.add(m);
+                pushedNames.add(m.name);
+                progressed = true;
+            }
+        }
+    }
+    if (ordered.length < manifests.length) {
+        // 仅「未放置且依赖永不齐全」的真实依赖环落入此分支（重名已被 pushedNames 消化）
+        const cyclic = [...new Set(manifests.filter(m => !pushed.has(m)).map(m => m.name))];
+        throw new Error(`CAR-E-DEPCYCLE: dependency cycle among [${cyclic.join(', ')}] (peer 边成环，拓扑排序中止)`);
+    }
+    return ordered;
+}
+// ==================== 热重载（SQ-05：car reload） ====================
+/** 报告 → stdout 行（CLI 打印用；PASS/FAIL + 定位 + 耗时） */
+export function formatLoadReport(report) {
+    const lines = [];
+    lines.push(`加载报告 installId=${report.installId} startedTime=${report.startedTime}`);
+    for (const s of report.stages) {
+        let line = `  [${s.stage.padEnd(8)}] ${s.status}`;
+        if (s.error)
+            line += ` — ${s.error.reason} (file: ${s.error.file})`;
+        if (s.conflicts?.length) {
+            line += ' — ' + s.conflicts.map(c => `${c.file}: peer ${c.peer}@${c.range} required but ${c.installed ?? '<missing>'} installed (path: ${c.path})`).join('; ');
+        }
+        lines.push(line);
+    }
+    lines.push(`  durationMs=${report.durationMs} warnings=${report.warnings.length}`);
+    for (const w of report.warnings)
+        lines.push(`  ⚠ ${w}`);
+    return lines;
+}
+/** 热重载会话：持有 epoch 与实例注册表，reload() 重走五阶段并 invalidate 旧实例 */
+export class ReloadManager {
+    #epoch = 0;
+    #instances = [];
+    #reports = [];
+    get epoch() { return this.#epoch; }
+    get instances() { return this.#instances; }
+    get history() { return this.#reports; }
+    /**
+     * SQ-05 时序：epoch+1 击穿缓存 → invalidate 旧实例（旧 ctx 后续访问抛 CAR-INVALIDATED）
+     * → 重走 discover→register → 五阶段报告。任一阶段 FAIL 即返回 FAIL 报告（旧实例已失效，
+     * 不做静默回退——加载期显式失败红线）。
+     */
+    async reload(source, opts = {}) {
+        this.#epoch += 1;
+        for (const old of this.#instances)
+            old.invalidate();
+        const result = await loadPlugins({ ...opts, source, reloadEpoch: this.#epoch });
+        this.#instances = result.plugins;
+        this.#reports = [...this.#reports, result.report];
+        return result;
+    }
+}

package/dist/load/sigGate.d.ts

@@ -0,0 +1,22 @@
+import type { AllowedLabels, CounterName } from '../telemetry/metrics.ts';
+export interface SignatureGateOptions {
+    /** 缺省 'warn'（DEC-1 ②：1.0 以 warn 发布，宽限期到期翻转为 enforce = 计划内默认值变更） */
+    mode?: 'warn' | 'enforce';
+    /** 信任锚公钥（ed25519 spki base64）；缺省走 CAR_TRUST_ROOT env，无则全部按 unsigned 处理 */
+    trustRootPublicKey?: string;
+    /** S20 §4 路径②：显式声明豁免（workspace 生效；warn 缺签路径计数 confirmed=yes，横幅保留） */
+    unsignedAllow?: boolean;
+    /** 零内容计数桥（metrics.ts Counters.onCount 兼容；labels 仅枚举，禁路径/内容） */
+    onCount?: (name: CounterName, labels?: AllowedLabels) => void;
+}
+export interface SigGateResult {
+    allowed: boolean;
+    warning?: string;
+    error?: string;
+    /** 入口文件裸字节 sha256 hex（读取失败时缺省）——横幅指纹与审计留痕用 */
+    manifestHash?: string;
+}
+/** env 配置通道（与 CAR_OFFLINE/CAR_REGISTRY_URL 同为先例）：CAR_SIG_ENFORCE/CAR_TRUST_ROOT/CAR_UNSIGNED_ALLOW */
+export declare function gateDepsFromEnv(env?: NodeJS.ProcessEnv): SignatureGateOptions;
+/** 单插件文件签名门：读文件算指纹 → 读 sidecar → verifier 判定（装载前三段第一道，先于任何模块执行） */
+export declare function verifyPluginFile(file: string, opts?: SignatureGateOptions): SigGateResult;

package/dist/load/sigGate.js

@@ -0,0 +1,68 @@
+/**
+ * M5-S28 · 装载签名门（sigGate）：verifier 的装载接线层（fs 层；verifier 保持纯验签、无 I/O）
+ *
+ * 口径：
+ *  - 被签物锚定：manifestHash = sha256(插件入口 .ts 文件裸字节) 的 hex 串。manifest 是运行时对象
+ *    （parse 阶段 import() 后才存在），无独立 manifest 文件字节可签——对入口文件整字节求哈希
+ *    同时覆盖 manifest 声明与全部代码，即宽限文本承诺的「manifestHash 指纹」。被签消息 =
+ *    hex 字符串的 UTF-8 字节（verifyMinisig Buffer.from(manifestHash) 口径；registry-e2e
+ *    run-e2e.ts「对制品原始字节求 sha256 再签 hex 串」先例同源）。哈希对裸字节求
+ *    （release-pipeline G-11 教训：禁止对编码文本求哈希）。
+ *  - 签名载体：sidecar `<file>.minisig`（ed25519 签名 base64，唯一实装轨）；sigstore 主轨
+ *    维持 verifier 骨架期预留（SignatureBundle.sigstoreBundle），sidecar 命名随主轨实装再登记。
+ *  - 门禁语义（ADR-003 / DEC-1 ②，2026-09-26 裁决）：缺省 mode=warn——缺签=横幅放行+指纹兜底
+ *    +计数 confirmed=no；mode=enforce——缺签硬拒绝；有签名但验签失败=硬拒绝（不可配置放行，
+ *    unsignedAllow 亦不豁免）。
+ *  - unsignedAllow（S20 §4 路径②：workspace 显式声明豁免）：仅作用于 warn 缺签路径——
+ *    计数改写 confirmed=yes（S20 §1 口径：yes=显式确认豁免动作后），横幅保留不消失。
+ *  - 信任根交付：CAR_TRUST_ROOT env（ed25519 spki，base64）或显式入参。缺省无信任根 =
+ *    全部插件按 unsigned 处理（warn 下横幅显式可见；enforce 下全部拒绝属 fail-closed，非静默）。
+ *  - 计数桥：onCount 采用 metrics.ts 宽签名（CounterName）；对 verifier 的窄回调参数做
+ *    适配包装（宽回调不能直接赋给 verifier 的窄参数位——strictFunctionTypes 逆变）。
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { enforceSignature } from './verifier.js';
+/** env 配置通道（与 CAR_OFFLINE/CAR_REGISTRY_URL 同为先例）：CAR_SIG_ENFORCE/CAR_TRUST_ROOT/CAR_UNSIGNED_ALLOW */
+export function gateDepsFromEnv(env = process.env) {
+    return {
+        mode: env.CAR_SIG_ENFORCE === '1' ? 'enforce' : 'warn',
+        trustRootPublicKey: env.CAR_TRUST_ROOT || undefined,
+        unsignedAllow: env.CAR_UNSIGNED_ALLOW === '1',
+    };
+}
+/** 单插件文件签名门：读文件算指纹 → 读 sidecar → verifier 判定（装载前三段第一道，先于任何模块执行） */
+export function verifyPluginFile(file, opts = {}) {
+    let manifestHash;
+    try {
+        manifestHash = createHash('sha256').update(readFileSync(file)).digest('hex');
+    }
+    catch (e) {
+        return { allowed: false, error: `CAR-E-SIG: plugin file unreadable — ${e.message}` };
+    }
+    let minisig;
+    const sidecar = `${file}.minisig`;
+    if (existsSync(sidecar)) {
+        try {
+            const raw = readFileSync(sidecar, 'utf-8').trim();
+            if (raw)
+                minisig = raw;
+        }
+        catch (e) {
+            // sidecar 存在但不可读 = 环境失败，fail-closed 显式拒绝（不静默降级为 unsigned）
+            return { allowed: false, manifestHash, error: `CAR-E-SIG: sidecar unreadable — ${e.message}` };
+        }
+    }
+    // 显式豁免改写：S20 §1 confirmed=yes = 显式确认豁免动作后（仅 warn 缺签路径会被 verifier 计数）
+    const onCount = opts.unsignedAllow
+        ? (name, labels) => opts.onCount?.(name, { ...labels, confirmed: 'yes' })
+        : (name, labels) => opts.onCount?.(name, labels);
+    const deps = {
+        trustRootPublicKey: opts.trustRootPublicKey ?? '',
+        mode: opts.mode ?? 'warn',
+    };
+    const r = enforceSignature(manifestHash, minisig ? { minisig } : undefined, deps, onCount);
+    // 横幅附指纹前缀：宽限文本承诺的「manifestHash 指纹兜底」在告警面可见（前 12 hex 位）
+    const warning = r.warning ? `${r.warning} [fp:${manifestHash.slice(0, 12)}]` : undefined;
+    return { allowed: r.allowed, warning, error: r.error, manifestHash };
+}

package/dist/load/sign.d.ts

@@ -0,0 +1,25 @@
+export interface SigningKeypair {
+    /** PKCS8 DER 私钥字节（写 <前缀>.priv；离线保管不入仓库——secrets 红线） */
+    privateKeyDer: Buffer;
+    /** SPKI DER base64 公钥（写 <前缀>.pub；即 CAR_TRUST_ROOT 信任根值） */
+    publicKeyBase64: string;
+}
+/** ed25519 签名密钥对生成（指南 §2 第 1 步 node -e 流程固化） */
+export declare function generateSigningKeypair(): SigningKeypair;
+export interface SignResult {
+    file: string;
+    sidecar: string;
+    /** 文件裸字节 sha256 hex（横幅指纹与审计留痕口径同 sigGate.manifestHash） */
+    manifestHash: string;
+}
+/** 对单文件签名并写 sidecar `<file>.minisig`（指南 §2 第 2 步 node -e 流程固化） */
+export declare function signPluginFile(file: string, privateKeyDer: Buffer): SignResult;
+/** 信任根解析（plugin-sign verify 用）：显式 flag > CAR_TRUST_ROOT env > <前缀>.pub 文件 */
+export declare function resolveTrustRoot(opts: {
+    flag?: string;
+    env?: NodeJS.ProcessEnv;
+    pubFilePath?: string;
+}): {
+    value?: string;
+    source: 'flag' | 'env' | 'pubfile' | 'none';
+};

package/dist/load/sign.js

@@ -0,0 +1,47 @@
+/**
+ * 1.1-S1 · plugin-sign 签名原语（keygen / sign 纯函数；verify 复用 sigGate.verifyPluginFile）
+ *
+ * 口径（与 M2-S6 verifier / M5-S28 sigGate 签验同源，逐字对齐签名强制启用指南 §2）：
+ *  - 被签物 = 插件入口 .ts 文件裸字节 sha256 的 hex 串；被签消息 = hex 字符串的 UTF-8 字节
+ *    （sigGate.ts 头注释同源；哈希对裸字节求——G-11 教训：禁止对编码文本求哈希）
+ *  - 私钥 = ed25519 PKCS8 DER 文件（<前缀>.priv）；公钥 = SPKI DER base64（<前缀>.pub，
+ *    即 CAR_TRUST_ROOT 信任根值）；sidecar = `<file>.minisig` 单段 base64（sigGate 读取口径）
+ *  - 本模块只产出密钥与签名；门禁判定（warn/enforce 分级、fail-closed 分级）在 verifier/sigGate——
+ *    sign 不判门。边界登记（1.1 规划 W2-1）：minisign 离线单轨；sigstore keyless 主轨延后（1.2 候选）
+ */
+import { createHash, generateKeyPairSync, sign as cryptoSign } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+/** ed25519 签名密钥对生成（指南 §2 第 1 步 node -e 流程固化） */
+export function generateSigningKeypair() {
+    const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+    return {
+        privateKeyDer: privateKey.export({ type: 'pkcs8', format: 'der' }),
+        publicKeyBase64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+    };
+}
+/** 对单文件签名并写 sidecar `<file>.minisig`（指南 §2 第 2 步 node -e 流程固化） */
+export function signPluginFile(file, privateKeyDer) {
+    const manifestHash = createHash('sha256').update(readFileSync(file)).digest('hex');
+    const minisig = cryptoSign(null, Buffer.from(manifestHash), { key: privateKeyDer, format: 'der', type: 'pkcs8' }).toString('base64');
+    const sidecar = `${file}.minisig`;
+    writeFileSync(sidecar, minisig);
+    return { file, sidecar, manifestHash };
+}
+/** 信任根解析（plugin-sign verify 用）：显式 flag > CAR_TRUST_ROOT env > <前缀>.pub 文件 */
+export function resolveTrustRoot(opts) {
+    if (opts.flag)
+        return { value: opts.flag, source: 'flag' };
+    const envVal = opts.env?.CAR_TRUST_ROOT;
+    if (envVal)
+        return { value: envVal, source: 'env' };
+    const pub = opts.pubFilePath;
+    if (pub) {
+        try {
+            const v = readFileSync(pub, 'utf-8').trim();
+            if (v)
+                return { value: v, source: 'pubfile' };
+        }
+        catch { /* pub 文件不可读 → 视同未提供，由调用方显式报错 */ }
+    }
+    return { value: undefined, source: 'none' };
+}

package/dist/load/verifier.d.ts

@@ -0,0 +1,35 @@
+export interface SignatureBundle {
+    /** minisign 式离线轨：对 manifestHash 的 ed25519 签名（base64） */
+    minisig?: string;
+    /** Sigstore keyless 主轨：离线 bundle（S6 接口预留——bundle 校验需生态依赖，M3/沙箱外实装） */
+    sigstoreBundle?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    track: 'minisign' | 'sigstore' | 'none';
+    error?: string;
+}
+export interface VerifierDeps {
+    /** 信任锚公钥（ed25519，base64；内置根 pinning 或 trustRoot 替换点） */
+    trustRootPublicKey: string;
+    /** D-2：S6-S9 = warn，S10 起 = enforce */
+    mode: 'warn' | 'enforce';
+    /** Sigstore 主轨探针（骨架期返回 false → 回退静态轨，复现 ADR-003 回退语义） */
+    sigstoreAvailable?: () => boolean;
+}
+/** 静态轨：ed25519 验证 manifestHash 签名 */
+export declare function verifyMinisig(manifestHash: string, minisig: string, trustRootPublicKey: string): {
+    ok: boolean;
+    error?: string;
+};
+/**
+ * 验签入口（装载前调用，A010001 之前的供应链第一道门）：
+ * 返回 { allowed, warning? }——warning 非空时调用方必须告警放行并留痕（enforce 前过渡期）
+ */
+export declare function enforceSignature(manifestHash: string, sig: SignatureBundle | undefined, deps: VerifierDeps, onCount?: (name: 'car_unsigned_confirmed', labels: {
+    confirmed: 'yes' | 'no';
+}) => void): {
+    allowed: boolean;
+    warning?: string;
+    error?: string;
+};

package/dist/load/verifier.js

@@ -0,0 +1,56 @@
+/**
+ * S6 验签器（ADR-003 双轨实装）：minisign 离线轨（node:crypto ed25519）+ Sigstore 接口预留
+ *
+ * fail-closed 分级（D-2 裁决）：
+ *  - 校验失败（有签名但不对）= 硬拒绝，不可配置放行
+ *  - 签名缺失 = warn 模式告警放行（manifestHash 兜底）→ enforce 模式硬拒绝
+ *  - Sigstore 轨不可达 = 回退静态轨；双轨皆败按缺失处理
+ *
+ * 接线登记（M5-S28，2026-09-26）：本模块自 S6 入库即为纯验签函数；装载路径接线由
+ * sigGate.ts（fs 层：文件指纹 + sidecar + env 配置）与 loadPlugins verify 阶段 /
+ * car run 直载门完成——verify 先于 parse 的 import()，模块执行前拦截。
+ * manifestHash 锚定口径 = sha256(插件入口文件裸字节) hex（被签消息 = hex 串 UTF-8 字节），
+ * 详见 sigGate.ts 头注释。本文件 API 面不变（s6/s17 契约冻结）。
+ */
+import { verify, createPublicKey } from 'node:crypto';
+/** 静态轨：ed25519 验证 manifestHash 签名 */
+export function verifyMinisig(manifestHash, minisig, trustRootPublicKey) {
+    try {
+        const key = createPublicKey({ key: Buffer.from(trustRootPublicKey, 'base64'), format: 'der', type: 'spki' });
+        const ok = verify(null, Buffer.from(manifestHash), key, Buffer.from(minisig, 'base64'));
+        return ok ? { ok: true } : { ok: false, error: 'signature mismatch' };
+    }
+    catch (e) {
+        return { ok: false, error: `verify error: ${String(e)}` };
+    }
+}
+/**
+ * 验签入口（装载前调用，A010001 之前的供应链第一道门）：
+ * 返回 { allowed, warning? }——warning 非空时调用方必须告警放行并留痕（enforce 前过渡期）
+ */
+export function enforceSignature(manifestHash, sig, deps, onCount) {
+    // 主轨探针：可用则先走 Sigstore（S6 骨架期默认不可用 → 回退静态轨）
+    if (deps.sigstoreAvailable?.()) {
+        if (sig?.sigstoreBundle) {
+            // bundle 校验需生态依赖（@sigstore/verify），骨架期视为不可达 → 回退静态轨（ADR-003 回退语义）
+        }
+        else if (deps.mode === 'enforce') {
+            return { allowed: false, error: 'CAR-E-SIG: sigstore bundle missing (enforce mode)' };
+        }
+    }
+    // 静态轨
+    if (sig?.minisig) {
+        const r = verifyMinisig(manifestHash, sig.minisig, deps.trustRootPublicKey);
+        if (r.ok)
+            return { allowed: true };
+        // 有签名但校验失败 = 硬拒绝（不可配置放行——ADR-003 fail-closed 第一级）
+        return { allowed: false, error: `CAR-E-SIG: signature verification FAILED: ${r.error}（不可配置放行）` };
+    }
+    // 签名缺失
+    if (deps.mode === 'enforce') {
+        return { allowed: false, error: 'CAR-E-SIG: signature missing (enforce mode)——manifestHash 指纹兜底不替代签名' };
+    }
+    // S17 采集面：unsigned 路径计数（零内容 labels；confirmed=no=未确认 warn / yes=显式确认豁免动作）
+    onCount?.('car_unsigned_confirmed', { confirmed: 'no' });
+    return { allowed: true, warning: 'CAR-W-SIG: unsigned plugin（warn 过渡期放行，manifestHash 指纹兜底；enforce 切换见 D-2 终局条件）' };
+}