@n2world/orchestrator 1.1.0

package/dist/mcp-client-guard.js

@@ -0,0 +1,179 @@
+"use strict";
+// ============================================================================
+// v2.5.2 Phase 6 — MCP 클라이언트 가드 + A2UI 격리 헬퍼
+// ----------------------------------------------------------------------------
+// 계획서 v2.5.2 §3.4/§보안: 외부 MCP 도구는 신뢰 불가 — 허용목록·SSRF 가드·출력
+// 스키마 검증·프롬프트 인젝션 필터. A2UI는 sandboxed iframe + 엄격 CSP + provenance.
+// (Macaroon=권한 위임, 본 모듈=오염 차단 — 분리 적용.)
+//
+// 정직 고지(제1계명): 본 모듈은 *정책/검증 로직*이며 테스트로 검증된다. 실제 브라우저
+// 렌더링(iframe/CSP 강제)은 런타임에서 본 헬퍼가 생성한 정책을 적용해야 효력이 있다.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A2UI_SANDBOX = void 0;
+exports.isSafeMcpUrl = isSafeMcpUrl;
+exports.isPrivateIp = isPrivateIp;
+exports.isSafeResolvedUrl = isSafeResolvedUrl;
+exports.sanitizeToolOutput = sanitizeToolOutput;
+exports.a2uiCsp = a2uiCsp;
+exports.provenanceBanner = provenanceBanner;
+// ── MCP 서버 허용목록 + SSRF 가드 ───────────────────────────────────────────
+const dns_1 = require("dns");
+const net = __importStar(require("net"));
+const PRIVATE_HOST = /^(localhost|127\.|0\.0\.0\.0|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|\[?::1\]?|\[?fe80:)/i;
+const METADATA_HOST = /(169\.254\.169\.254|metadata\.google\.internal|metadata\.azure)/i;
+function isSafeMcpUrl(url, allowHosts) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: 'URL 파싱 실패' };
+    }
+    if (u.protocol !== 'https:')
+        return { ok: false, reason: 'https 아님(평문 차단)' };
+    if (PRIVATE_HOST.test(u.hostname))
+        return { ok: false, reason: `사설/루프백 호스트 차단(${u.hostname})` };
+    if (METADATA_HOST.test(u.hostname))
+        return { ok: false, reason: '클라우드 메타데이터 엔드포인트 차단(SSRF)' };
+    if (!allowHosts.includes(u.hostname))
+        return { ok: false, reason: `허용목록 외 호스트(${u.hostname})` };
+    return { ok: true, reason: 'ok' };
+}
+/** M2 — IP 가 사설/루프백/링크로컬/메타데이터/유니크로컬인가(SSRF 표적). */
+function isPrivateIp(ip) {
+    const v = ip.trim().toLowerCase().replace(/^::ffff:/, ''); // IPv4-mapped 정규화
+    if (net.isIPv4(v)) {
+        const o = v.split('.').map(Number);
+        if (o[0] === 127 || o[0] === 10 || o[0] === 0)
+            return true; // 루프백/사설/this-network
+        if (o[0] === 192 && o[1] === 168)
+            return true; // 사설
+        if (o[0] === 172 && o[1] >= 16 && o[1] <= 31)
+            return true; // 사설
+        if (o[0] === 169 && o[1] === 254)
+            return true; // 링크로컬/메타데이터
+        if (o[0] === 100 && o[1] >= 64 && o[1] <= 127)
+            return true; // CGNAT
+        return false;
+    }
+    if (net.isIPv6(v)) {
+        if (v === '::1' || v === '::')
+            return true; // 루프백/미지정
+        if (v.startsWith('fe80'))
+            return true; // 링크로컬
+        if (v.startsWith('fc') || v.startsWith('fd'))
+            return true; // 유니크 로컬(ULA)
+        return false;
+    }
+    return true; // 알 수 없는 형식은 안전측으로 차단
+}
+/**
+ * M2 — DNS 리바인딩 방지: 호스트명을 *실제 resolve* 한 뒤 모든 IP가 공인인지 검사.
+ * 허용/공개 호스트명이 사설 IP로 가리켜도 차단. 외부 연결 직전 호출.
+ */
+async function isSafeResolvedUrl(url, allowHosts, resolver) {
+    const base = isSafeMcpUrl(url, allowHosts);
+    if (!base.ok)
+        return base;
+    const host = new URL(url).hostname.replace(/^\[|\]$/g, '');
+    // 호스트명이 곧 IP면 그대로 검사(추가 resolve 불요).
+    if (net.isIP(host)) {
+        return isPrivateIp(host) ? { ok: false, reason: `사설/예약 IP 차단(${host})` } : { ok: true, reason: 'ok' };
+    }
+    let ips;
+    try {
+        ips = resolver ? await resolver(host) : (await dns_1.promises.lookup(host, { all: true })).map((a) => a.address);
+    }
+    catch (e) {
+        return { ok: false, reason: `DNS resolve 실패(${host}): ${e?.code ?? e?.message ?? 'err'}` };
+    }
+    if (!ips.length)
+        return { ok: false, reason: `resolve 결과 없음(${host})` };
+    const bad = ips.find((ip) => isPrivateIp(ip));
+    if (bad)
+        return { ok: false, reason: `DNS 리바인딩 의심 — 사설 IP로 resolve(${host}→${bad})` };
+    return { ok: true, reason: 'ok' };
+}
+// ── 도구 출력 오염 검증(신뢰 불가 입력) ─────────────────────────────────────
+const INJECTION_PATTERNS = [
+    /ignore (previous|above) instructions/i,
+    /system prompt/i,
+    /you are now/i,
+    /<\s*script/i,
+    /\bexfiltrat/i,
+];
+/**
+ * MCP 도구 출력 검증: (1) 기대 스키마 검증, (2) 프롬프트 인젝션 패턴 플래그.
+ * 인젝션 패턴이 있으면 ok=false(에이전트 컨텍스트로 환류 금지).
+ */
+function sanitizeToolOutput(raw, isValid) {
+    const flags = [];
+    for (const re of INJECTION_PATTERNS)
+        if (re.test(raw))
+            flags.push(`injection:${re.source.slice(0, 24)}`);
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, flags: [...flags, 'schema:JSON 파싱 실패'] };
+    }
+    if (!isValid(data))
+        flags.push('schema:불일치');
+    return { ok: flags.length === 0, data: flags.length === 0 ? data : undefined, flags };
+}
+// ── A2UI 격리 정책(CSP) + provenance ────────────────────────────────────────
+/** 에이전트 생성 캔버스용 엄격 CSP — 인라인·eval·임의 네트워크 차단(허용 출처만). */
+function a2uiCsp(allowConnect = []) {
+    const connect = ["'self'", ...allowConnect].join(' ');
+    return [
+        "default-src 'none'",
+        "script-src 'self'", // 인라인/eval 금지
+        "style-src 'self'",
+        "img-src 'self' data:",
+        `connect-src ${connect}`, // 임의 네트워크 금지(허용목록만)
+        "frame-ancestors 'self'",
+        "base-uri 'none'",
+        "form-action 'self'",
+    ].join('; ');
+}
+/** iframe sandbox 속성 — 동일출처/팝업/탑네비 차단(스크립트만 허용). */
+exports.A2UI_SANDBOX = 'allow-scripts';
+/** provenance 배너 마크업 — 사용자에게 "에이전트 생성" 출처를 명시(기만 방지). */
+function provenanceBanner() {
+    return '<div role="note" data-n2world-provenance="agent-generated" style="position:sticky;top:0;background:#fde68a;color:#111;padding:6px 10px;font:600 12px sans-serif">⚠ 이 화면은 에이전트가 생성했습니다 — 입력 전 출처를 확인하세요</div>';
+}

package/dist/mcp-macaroon.d.ts

@@ -0,0 +1,75 @@
+import { A2ATrustGate } from './agent-os-rd';
+import { DataTier, Destination, TierGuard, ConsentGate, ConsentScope } from './beta';
+export interface McpToolCall {
+    id: string;
+    /** MCP 도구 이름(= Macaroon scope·target). */
+    tool: string;
+    /** 데이터/행동 민감도 Tier. */
+    dataTier: DataTier;
+    /** 데이터 목적지. */
+    destination: Destination;
+    userId: string;
+    /** 선택적 경로 범위(path caveat 검증용). */
+    path?: string;
+}
+export interface AuthorizeOptions {
+    /** 외부 전송 시 요구할 동의 범위(기본 'llm-transmission'). */
+    requireConsentScope?: ConsentScope;
+    /** A2A 신뢰 평가용 peer id(있으면 신뢰 t 게이트 적용). */
+    peerId?: string;
+    /**
+     * 행동의 MCTS 계획 가치 v(있어도 인가 결정에 쓰지 않는다 — v↔t 분리 증명용 기록만).
+     * 고가치라도 저신뢰면 차단됨을 보이기 위해 받되, 게이트 로직은 v 를 참조하지 않는다.
+     */
+    value?: number;
+}
+export interface AuthorizationResult {
+    id: string;
+    allowed: boolean;
+    reason: string;
+    /** Macaroon 서명+target+expires 검증(HARD_GATE). */
+    hardGate: boolean;
+    /** 호출 도구가 Macaroon scope 와 일치. */
+    scopeOk: boolean;
+    /** 호출 dataTier 가 Macaroon tier 상한 이하. */
+    tierOk: boolean;
+    /** Tier-0 외부 반출 차단 통과(egress 허용 여부). */
+    egressAllowed: boolean;
+    /** Tier-0 외부 반출이 실제로 차단됐는가(관측 0/N 의 분자). */
+    tier0ExfilBlocked: boolean;
+    /** Tier 별 동의 충족. */
+    consentOk: boolean;
+    /** 신뢰 t(peerId 주어졌을 때). 아니면 null. */
+    trust: number | null;
+    /** 기록용(인가에 미사용) — v↔t 분리 증명. */
+    value: number | null;
+}
+/** MCP 도구 호출용 Macaroon 발행 — target=tool, scope=tool, tier 상한, 만료 caveat. */
+export declare class MCPMacaroonMinter {
+    private readonly secret;
+    constructor(secret: string);
+    /**
+     * 사용자에게 도구 호출 Macaroon 을 발행한다. tier 상한 이하의 데이터에만 쓸 수 있고,
+     * scope(도구)·만료가 caveat 으로 묶인다(이후 attenuate 로만 추가 제한 가능 — 권한 상승 불가).
+     */
+    mint(userId: string, tool: string, tierCeiling: DataTier, expiresAtMs: number): string;
+}
+/**
+ * MCP 호출 경계 인가자. Macaroon(scope·tier·만료) + Tier 동의 + Tier-0 반출 차단 + 신뢰 t 를 결선한다.
+ * TierGuard/ConsentGate 는 B0 와 공유해 동의 체계를 중복하지 않는다(생성자 주입).
+ */
+export declare class MCPAuthorizer {
+    private readonly secret;
+    private readonly tierGuard;
+    private readonly consent;
+    private readonly trustGate?;
+    constructor(secret: string, tierGuard?: TierGuard, consent?: ConsentGate, trustGate?: A2ATrustGate | undefined);
+    /** Tier-0 외부 반출 관측 통계(`관측 0/N`) — tier0ExfilObserved 는 항상 0 이어야 한다. */
+    egressStats(): {
+        externalAttempts: number;
+        tier0ExternalAttempts: number;
+        tier0ExfilObserved: number;
+    };
+    consentGate(): ConsentGate;
+    authorize(call: McpToolCall, token: string, opts?: AuthorizeOptions): AuthorizationResult;
+}

package/dist/mcp-macaroon.js

@@ -0,0 +1,161 @@
+"use strict";
+// ============================================================================
+// P5 — MCP-Macaroon 인가 + Tier 0/1/2 동의 (계획서 v2.4 §7 P5, 헌법 §2 신뢰 t)
+// ----------------------------------------------------------------------------
+// MCP(도구 연동) 호출 경계에 Macaroon 인가를 결선한다. 재사용(새 체계 금지·단순화):
+//   - `agent-os-rd.ts`: Macaroon/MacaroonVerifier(서명 체인·target·expires) + A2ATrustGate(신뢰 t)
+//   - `beta.ts`(B0): DataTier·TierGuard(Tier-0 반출 차단·관측 0/N) + ConsentGate(동의)
+//
+// 핵심 보장:
+//   1) MCP 호출은 Macaroon 의 scope(도구)·tier 상한 caveat 로 인가된다(서명으로 무결성 보호).
+//   2) 데이터/행동을 Tier 0/1/2 로 분류, Tier 별 동의 게이트 강제. **중복 동의 체계를 만들지 않는다.**
+//   3) **Tier-0 데이터의 외부 반출은 무조건 차단 → `관측 0/N`**(TierGuard 가 실측 카운트).
+//   4) 신뢰 t = HARD_GATE × reputation. **고가치(v)·저신뢰(t) 는 차단** — v 로 계층1 을 게이팅하지 않는다.
+//
+// 정직 고지(제1계명): `tier <=`·`scope =` caveat 는 Macaroon 서명 체인에 포함되어 무결성 보호되며,
+//   MacaroonVerifier(서명+target+expires) 통과 후 본 인가자가 의미를 강제한다. 위조/범위 밖은 차단.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPAuthorizer = exports.MCPMacaroonMinter = void 0;
+const agent_os_rd_1 = require("./agent-os-rd");
+const beta_1 = require("./beta");
+const CAVEAT_TIER = 'tier <= ';
+const CAVEAT_SCOPE = 'scope = ';
+/** MCP 도구 호출용 Macaroon 발행 — target=tool, scope=tool, tier 상한, 만료 caveat. */
+class MCPMacaroonMinter {
+    secret;
+    constructor(secret) {
+        this.secret = secret;
+    }
+    /**
+     * 사용자에게 도구 호출 Macaroon 을 발행한다. tier 상한 이하의 데이터에만 쓸 수 있고,
+     * scope(도구)·만료가 caveat 으로 묶인다(이후 attenuate 로만 추가 제한 가능 — 권한 상승 불가).
+     */
+    mint(userId, tool, tierCeiling, expiresAtMs) {
+        let m = agent_os_rd_1.Macaroon.create(this.secret, userId, tool); // target = tool
+        m = agent_os_rd_1.Macaroon.attenuate(m, `${CAVEAT_TIER}${tierCeiling}`);
+        m = agent_os_rd_1.Macaroon.attenuate(m, `${CAVEAT_SCOPE}${tool}`);
+        m = agent_os_rd_1.Macaroon.attenuate(m, `expires < ${expiresAtMs}`);
+        return agent_os_rd_1.Macaroon.serialize(m);
+    }
+}
+exports.MCPMacaroonMinter = MCPMacaroonMinter;
+/**
+ * Macaroon caveat 에서 tier 상한·scope 를 파싱(없으면 null).
+ *
+ * 보안(attenuation 단조성): Macaroon 보유자는 root secret 없이 `attenuate` 로 caveat 를
+ * **덧붙일 수 있고** 서명 체인은 그대로 검증을 통과한다. 따라서 `tier <= 0` 토큰에
+ * `tier <= 2` 를 덧붙여 권한을 넓히는 시도가 가능하다. caveat 는 **제한만** 할 수 있어야
+ * 하므로, 여러 `tier <= ` caveat 이 있으면 **최솟값(가장 제한적)** 을 취한다(last-wins 금지).
+ */
+function parseCaveats(token) {
+    try {
+        const m = agent_os_rd_1.Macaroon.deserialize(token);
+        let tierCeiling = null;
+        let scope = null;
+        for (const c of m.caveats) {
+            if (c.startsWith(CAVEAT_TIER)) {
+                const n = parseInt(c.substring(CAVEAT_TIER.length), 10);
+                // 가장 제한적(min)으로만 좁힌다 — 덧붙인 더 느슨한 상한으로 권한 상승 불가.
+                if (n === 0 || n === 1 || n === 2) {
+                    tierCeiling = tierCeiling === null ? n : Math.min(tierCeiling, n);
+                }
+            }
+            else if (c.startsWith(CAVEAT_SCOPE)) {
+                // scope 도 동일 원칙: 한 번 정해진 scope 와 다른 값이 덧붙으면 충돌 → 차단(null).
+                // (scope 자체는 target caveat 이중검증으로도 보호되나, 방어심층화로 일관 적용.)
+                const s = c.substring(CAVEAT_SCOPE.length);
+                scope = scope === null ? s : scope === s ? s : '\0conflict';
+            }
+        }
+        return { tierCeiling, scope };
+    }
+    catch {
+        return { tierCeiling: null, scope: null };
+    }
+}
+/**
+ * MCP 호출 경계 인가자. Macaroon(scope·tier·만료) + Tier 동의 + Tier-0 반출 차단 + 신뢰 t 를 결선한다.
+ * TierGuard/ConsentGate 는 B0 와 공유해 동의 체계를 중복하지 않는다(생성자 주입).
+ */
+class MCPAuthorizer {
+    secret;
+    tierGuard;
+    consent;
+    trustGate;
+    constructor(secret, tierGuard = new beta_1.TierGuard(), consent = new beta_1.ConsentGate(), trustGate) {
+        this.secret = secret;
+        this.tierGuard = tierGuard;
+        this.consent = consent;
+        this.trustGate = trustGate;
+    }
+    /** Tier-0 외부 반출 관측 통계(`관측 0/N`) — tier0ExfilObserved 는 항상 0 이어야 한다. */
+    egressStats() {
+        return this.tierGuard.stats();
+    }
+    consentGate() {
+        return this.consent;
+    }
+    authorize(call, token, opts = {}) {
+        const now = Date.now();
+        const ctx = { target: call.tool, time: now, path: call.path ?? '' };
+        const base = {
+            id: call.id,
+            allowed: false,
+            reason: '',
+            hardGate: false,
+            scopeOk: false,
+            tierOk: false,
+            egressAllowed: false,
+            tier0ExfilBlocked: false,
+            consentOk: false,
+            trust: null,
+            value: opts.value ?? null,
+        };
+        // 1) HARD_GATE: Macaroon 서명 체인 + target(=tool) + expires 검증.
+        const hardGate = agent_os_rd_1.MacaroonVerifier.verify(token, this.secret, ctx);
+        base.hardGate = hardGate;
+        if (!hardGate) {
+            return { ...base, reason: 'HARD_GATE 실패: Macaroon 서명/target/만료 위반' };
+        }
+        // 2) scope·tier 상한 caveat 강제(서명으로 무결성 보호된 caveat).
+        const { tierCeiling, scope } = parseCaveats(token);
+        base.scopeOk = scope === call.tool;
+        if (!base.scopeOk) {
+            return { ...base, reason: `scope 불일치: 토큰 scope=${scope} ≠ 호출 도구=${call.tool}` };
+        }
+        base.tierOk = tierCeiling !== null && call.dataTier <= tierCeiling;
+        if (!base.tierOk) {
+            return { ...base, reason: `tier 상한 초과: 호출 Tier=${call.dataTier} > 토큰 상한=${tierCeiling}` };
+        }
+        // 3) Tier-0 외부 반출 차단(TierGuard — 관측 0/N). 모든 시도/차단은 실측 기록.
+        const eg = this.tierGuard.guardEgress(call.dataTier, call.destination);
+        base.egressAllowed = eg.allowed;
+        base.tier0ExfilBlocked = call.dataTier === 0 && call.destination === 'external' && !eg.allowed;
+        if (!eg.allowed) {
+            return { ...base, reason: eg.reason }; // Tier-0 외부 반출 차단(관측 0/N 보장)
+        }
+        // 4) Tier 동의: 외부 전송이면서 Tier-0 이 아닌 경우 동의 필요(Tier-0 은 이미 3에서 차단).
+        if (call.destination === 'external') {
+            const scopeNeeded = opts.requireConsentScope ?? 'llm-transmission';
+            base.consentOk = this.consent.hasConsent(call.userId, scopeNeeded);
+            if (!base.consentOk) {
+                return { ...base, reason: `동의 필요: ${scopeNeeded} (Tier ${call.dataTier} 외부 전송 — 미동의 차단)` };
+            }
+        }
+        else {
+            base.consentOk = true; // 로컬 목적지는 외부 동의 불요(헌법 제4조 로컬 기억)
+        }
+        // 5) 신뢰 t = HARD_GATE × reputation. **고가치라도 저신뢰면 차단**(v↔t 분리).
+        if (this.trustGate && opts.peerId) {
+            const r = this.trustGate.evaluate(opts.peerId, token, ctx);
+            base.trust = r.trust;
+            if (!r.allowed) {
+                // opts.value(고가치)는 결정에 쓰지 않는다 — 신뢰 t 만으로 차단.
+                return { ...base, reason: `신뢰 미달(t=${r.trust.toFixed(3)}) — 고가치라도 차단(v↔t 분리)` };
+            }
+        }
+        return { ...base, allowed: true, reason: 'authorized' };
+    }
+}
+exports.MCPAuthorizer = MCPAuthorizer;

package/dist/mcts-kernel-bridge.d.ts

@@ -0,0 +1,36 @@
+import { SchedulerConfig } from './agent-os-rd';
+export interface KernelControlResult {
+    /** 입력 정규화 가치 v_norm∈[0,1]. */
+    vNorm: number;
+    /** 식(2)로 계산한 의도 cgroups cpu.weight (플랫폼 무관, 항상 산출). */
+    weight: number;
+    /** 실제 cpu.weight 파일 기입 성공(Linux+유효 cgroup+권한만 true). 비-Linux=false(정직). */
+    cgroupWritten: boolean;
+    /** 실제 eBPF 맵 갱신 성공(Linux+CAP_BPF만 true). 비-Linux=false(정직). */
+    ebpfWritten: boolean;
+    /** eBPF 맵이 활성인가(Linux+권한). */
+    ebpfMapActive: boolean;
+    platform: string;
+    isLinux: boolean;
+    note: string;
+}
+/**
+ * MCTS 가치 → 커널 자원 제어 결선 브리지. v_norm 한 번으로 식(2) 가중치 산출 + cgroup/eBPF 기입을 모두 시도한다.
+ * 비-Linux 환경에선 의도 가중치만 계산하고 실기입은 정직하게 false 로 보고한다.
+ */
+export declare class MctsKernelBridge {
+    private driver;
+    private ebpf;
+    constructor(cfg?: Partial<SchedulerConfig>);
+    /** eBPF 맵 활성 여부(Linux+CAP_BPF). 비-Linux/비-권한이면 false. */
+    ebpfActive(): boolean;
+    /** 식(2)로 계산한 의도 가중치(플랫폼 무관). 기입 시도 없이 값만. */
+    weightFor(vNorm: number): number;
+    /**
+     * v_norm → 식(2) weight → cgroup cpu.weight 기입 + eBPF 맵(thread_id→v) 갱신.
+     * 경로를 끝까지 연결한다. 실기입 성공 여부는 플랫폼·권한에 따라 정직히 보고.
+     */
+    applyValue(cgroupPath: string, vNorm: number, threadId: number): KernelControlResult;
+    /** 원시 Q와 분포(min,max)로부터 정규화 후 결선. */
+    applyRawValue(cgroupPath: string, q: number, qMin: number, qMax: number, threadId: number): KernelControlResult;
+}

package/dist/mcts-kernel-bridge.js

@@ -0,0 +1,99 @@
+"use strict";
+// ============================================================================
+// P4 — MCTS 가치 v → 커널 자원 제어(cgroups/eBPF) 결선 (계획서 v2.4 §7 P4, §2.1)
+// ----------------------------------------------------------------------------
+// 가치 v_norm → 식(2) 가중치 w(v_norm) → cgroups cpu.weight 실기입 + eBPF 맵 갱신까지 **끝까지 결선**한다.
+// 재사용: `EbpfSchedulerDriver`(식(2)·set_cgroup_cpu_weight) + Rust `EbpfMapScheduler`(raw bpf() 맵).
+//
+// 정직 고지(제1계명): 가중치 w 는 플랫폼 무관하게 항상 계산(의도 제어)되지만, **실제 커널 기입은
+//   Linux + 권한에서만 true**다. 비-Linux/비-권한은 **정직하게 false**를 돌려준다(가짜 true 금지).
+//   과거 `update_ebpf_map`/`set_cgroup_cpu_weight` 가 true 반환 스텁이던 전력을 반복하지 않는다.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MctsKernelBridge = void 0;
+const os = __importStar(require("os"));
+const core_1 = require("@n2world/core");
+const agent_os_rd_1 = require("./agent-os-rd");
+/**
+ * MCTS 가치 → 커널 자원 제어 결선 브리지. v_norm 한 번으로 식(2) 가중치 산출 + cgroup/eBPF 기입을 모두 시도한다.
+ * 비-Linux 환경에선 의도 가중치만 계산하고 실기입은 정직하게 false 로 보고한다.
+ */
+class MctsKernelBridge {
+    driver;
+    ebpf;
+    constructor(cfg = {}) {
+        this.driver = new agent_os_rd_1.EbpfSchedulerDriver(cfg);
+        this.ebpf = new core_1.EbpfMapScheduler();
+    }
+    /** eBPF 맵 활성 여부(Linux+CAP_BPF). 비-Linux/비-권한이면 false. */
+    ebpfActive() {
+        return this.ebpf.mapActive();
+    }
+    /** 식(2)로 계산한 의도 가중치(플랫폼 무관). 기입 시도 없이 값만. */
+    weightFor(vNorm) {
+        return this.driver.weightForValue(vNorm);
+    }
+    /**
+     * v_norm → 식(2) weight → cgroup cpu.weight 기입 + eBPF 맵(thread_id→v) 갱신.
+     * 경로를 끝까지 연결한다. 실기입 성공 여부는 플랫폼·권한에 따라 정직히 보고.
+     */
+    applyValue(cgroupPath, vNorm, threadId) {
+        const isLinux = os.platform() === 'linux';
+        const { weight, success: cgroupWritten } = this.driver.adjustResourceByValue(cgroupPath, vNorm);
+        const ebpfWritten = this.ebpf.updateEbpfMap(threadId, Math.max(0, Math.min(1, vNorm)));
+        const ebpfMapActive = this.ebpf.mapActive();
+        return {
+            vNorm: Math.max(0, Math.min(1, vNorm)),
+            weight,
+            cgroupWritten,
+            ebpfWritten,
+            ebpfMapActive,
+            platform: os.platform(),
+            isLinux,
+            note: isLinux
+                ? cgroupWritten || ebpfWritten
+                    ? '커널 결선 활성(Linux): 실기입 성공.'
+                    : 'Linux 이나 권한/cgroup 경로 부재 — 의도 가중치만 적용(정직 false).'
+                : '비-Linux: 의도 가중치만 계산. cgroup/eBPF 실기입 없음(정직 false — 가짜 true 아님).',
+        };
+    }
+    /** 원시 Q와 분포(min,max)로부터 정규화 후 결선. */
+    applyRawValue(cgroupPath, q, qMin, qMax, threadId) {
+        const vNorm = agent_os_rd_1.EbpfSchedulerDriver.normalize(q, qMin, qMax);
+        return this.applyValue(cgroupPath, vNorm, threadId);
+    }
+}
+exports.MctsKernelBridge = MctsKernelBridge;

package/dist/mcts-prior.d.ts

@@ -0,0 +1,79 @@
+import { KnowledgeGraph } from './knowledge-graph';
+export interface ActionItem {
+    id: string;
+    content: string;
+}
+export interface ActionPrior {
+    id: string;
+    prior: number;
+}
+export interface EmbeddingPriorOptions {
+    /** softmax 온도(>0). 낮을수록 상위 후보 집중. */
+    temperature?: number;
+    /** P2 그래프(있으면) — 컨텍스트 관련 노드의 이웃 액션에 사전확률 부스트. */
+    graph?: KnowledgeGraph;
+    /** 그래프 부스트 배수(기본 1.5). 1 이면 부스트 없음. */
+    graphBoost?: number;
+    /** 그래프 부스트 기준 노드 id 들(보통 컨텍스트가 가리키는 항목). */
+    graphAnchors?: string[];
+}
+/**
+ * P1 임베딩 + (옵션)P2 그래프로 사전확률 P(s,a)를 만든다(합=1).
+ * graph/graphAnchors 가 주어지면, 앵커 노드와 참조/의존으로 연결된 액션의 prior 를 곱셈 부스트 후 재정규화.
+ */
+export declare function embeddingWeightedPrior(actions: ActionItem[], context: string, opts?: EmbeddingPriorOptions): ActionPrior[];
+/** 균등 사전확률(비교군 baseline). */
+export declare function uniformPrior(actions: ActionItem[]): ActionPrior[];
+interface ArmStat {
+    id: string;
+    n: number;
+    w: number;
+    prior: number;
+}
+/** 식(1) PUCT 선택: argmax[ Q + c_puct·P·√(ΣN)/(1+n) ]. */
+export declare function puctSelect(stats: ArmStat[], cPuct: number): ArmStat;
+export interface PuctSearchResult {
+    /** 가장 많이 방문된 액션이 target 과 처음 일치한 시뮬 번호(낮을수록 효율). 끝까지 불일치면 sims+1. */
+    simsToConverge: number;
+    /** 종료 시 최다 방문 액션. */
+    finalBestId: string;
+    /** target 액션의 누적 방문수. */
+    targetVisits: number;
+    /** 누적 후회(regret) = Σ(maxTrueValue − trueValue[선택]). 낮을수록 좋음. */
+    regret: number;
+}
+/**
+ * 사전확률 priors 로 PUCT 탐색을 sims 회 돌리고 효율 지표를 반환한다.
+ * 보상 = trueValue[선택] + 가우시안 잡음(외부 오라클). target = trueValue 최대 액션.
+ * @param rnd 결정적 난수(시드 고정) — 재현성.
+ */
+export declare function runPuctSearch(actions: ActionItem[], priors: ActionPrior[], trueValue: Record<string, number>, sims: number, cPuct: number, rnd: () => number, noiseSd?: number): PuctSearchResult;
+export interface PriorEfficiencyComparison {
+    uniform: {
+        simsToConvergeMean: number;
+        regretMean: number;
+        convergedRate: number;
+    };
+    embedding: {
+        simsToConvergeMean: number;
+        regretMean: number;
+        convergedRate: number;
+    };
+    /** 평균 수렴 시뮬 절감(uniform − embedding). 양수면 임베딩 사전확률이 더 빠름. */
+    simsToConvergeSaved: number;
+    trials: number;
+}
+/**
+ * 균등 vs 임베딩 사전확률의 PUCT 탐색 효율을 다회 비교한다(결정적 시드).
+ * trueValue 는 호출자가 주는 외부 오라클(임베딩과 독립적으로 정한 진짜 가치).
+ */
+export declare function comparePriorEfficiency(actions: ActionItem[], context: string, trueValue: Record<string, number>, opts?: {
+    sims?: number;
+    cPuct?: number;
+    trials?: number;
+    seed?: number;
+    priorOpts?: EmbeddingPriorOptions;
+}): PriorEfficiencyComparison;
+/** 결정적 LCG(시드 고정) — 재현 가능한 측정. */
+export declare function lcg(seed: number): () => number;
+export {};