@n2world/orchestrator 1.1.0

package/dist/dental-metrics.js

@@ -0,0 +1,37 @@
+"use strict";
+// ============================================================================
+// P5 — 치과 파일럿 이로움 계측 (앱 v1.2 §7 · 방안서 v1.1 §6) — 행동 프록시
+// ----------------------------------------------------------------------------
+// "측정된 이로움"(헌법 제1조)을 *행동 기반*으로 잰다 — 자가보고 만족은 보조.
+//   - 접수 처리시간(자동화 전/후), 완료율(오라클통과+사람승인), 대조 적중, 재방문.
+//
+// 정직 고지(제1계명): 계측 인프라(테스트 가능). 실 수치는 *실 치과 파일럿*에서 실측
+// (현재 (가정;미검증)). 개인정보는 로컬·익명 집계(외부 전송 없음).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DentalMetrics = void 0;
+exports.ltvCacGate = ltvCacGate;
+class DentalMetrics {
+    events = [];
+    record(e) { this.events.push(e); }
+    report() {
+        const n = this.events.length;
+        if (n === 0)
+            return { n: 0, timeSavedMsMean: 0, timeSavedPct: 0, completionRate: 0, flagHitRate: 0, satisfactionMean: null };
+        const savedArr = this.events.map((e) => e.baselineMs - e.actualMs);
+        const timeSavedMsMean = savedArr.reduce((a, b) => a + b, 0) / n;
+        const baseMean = this.events.reduce((a, e) => a + e.baselineMs, 0) / n;
+        const timeSavedPct = baseMean > 0 ? timeSavedMsMean / baseMean : 0;
+        const completionRate = this.events.filter((e) => e.completed).length / n;
+        const flagHitRate = this.events.filter((e) => e.flagHit).length / n;
+        const sats = this.events.map((e) => e.satisfaction).filter((s) => s != null);
+        const satisfactionMean = sats.length ? sats.reduce((a, b) => a + b, 0) / sats.length : null;
+        return { n, timeSavedMsMean, timeSavedPct: +timeSavedPct.toFixed(3), completionRate, flagHitRate, satisfactionMean };
+    }
+}
+exports.DentalMetrics = DentalMetrics;
+/** 유닛 이코노믹스 게이트: LTV/CAC ≥ 3 인가(파일럿 검증). */
+function ltvCacGate(ltv, cac, threshold = 3) {
+    const ratio = cac > 0 ? ltv / cac : Infinity;
+    return { pass: ratio >= threshold, ratio: +ratio.toFixed(2) };
+}

package/dist/docking.d.ts

@@ -0,0 +1,36 @@
+export interface MemoryItem {
+    id: string;
+    content: string;
+}
+/** 세션 컨텍스트 — 채널에 귀속된 대화 이력 + 임베딩 인덱스. */
+export declare class SessionContext {
+    channel: string;
+    readonly sessionId: string;
+    private items;
+    private vec;
+    constructor(channel: string, sessionId: string);
+    add(item: MemoryItem): void;
+    /** 질의와 가장 유사한 상위 k 항목 id(결정론적). */
+    topK(query: string, k?: number): string[];
+    size(): number;
+    snapshotItems(): MemoryItem[];
+}
+export interface DockResult {
+    session: SessionContext;
+    fromChannel: string;
+    toChannel: string;
+    latencyMs: number;
+}
+/**
+ * 도킹 — 동일 세션을 새 채널로 재귀속하되 이력·인덱스를 *그대로 이전*한다.
+ * (유실 없는 이전이 목표. 유실되면 §보존 측정에서 일치율 하락으로 드러난다.)
+ */
+export declare function dockTo(session: SessionContext, toChannel: string): DockResult;
+/** 도킹 전후 top-k 일치율(교집합/ k). 1.0 = 완전 보존. */
+export declare function preservationRatio(before: string[], after: string[]): number;
+/** N개 질의에 대한 평균 top-k 보존율(도킹 전후). */
+export declare function measurePreservation(session: SessionContext, queries: string[], toChannel: string, k?: number): {
+    meanRatio: number;
+    latencyMs: number;
+    n: number;
+};

package/dist/docking.js

@@ -0,0 +1,73 @@
+"use strict";
+// ============================================================================
+// v2.5.2 Phase S / Phase 1 — ChannelDocking + 보존 측정
+// ----------------------------------------------------------------------------
+// 계획서 v2.5.2 §3.1: 대화 중 수신 채널을 교체(도킹)하되 *대화 이력과 시맨틱 인덱스*를
+// 보존한다. 원안의 "100% 보존"은 금지 — 도킹 전후 top-k 검색 일치율을 *실측*한다.
+//
+// 본 모듈은 경량 임베딩(text-embedding 해시 코사인)으로 결정론적 top-k를 제공해
+// jest에서 네트워크/무거운 인덱스 없이 보존율을 측정한다(프로덕션은 HNSW 경로).
+// 정직 고지: 보존율은 측정값이며, 도킹이 인덱스를 *유실*하면 일치율이 떨어져 드러난다.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionContext = void 0;
+exports.dockTo = dockTo;
+exports.preservationRatio = preservationRatio;
+exports.measurePreservation = measurePreservation;
+const text_embedding_1 = require("./text-embedding");
+/** 세션 컨텍스트 — 채널에 귀속된 대화 이력 + 임베딩 인덱스. */
+class SessionContext {
+    channel;
+    sessionId;
+    items = [];
+    vec = new Map();
+    constructor(channel, sessionId) {
+        this.channel = channel;
+        this.sessionId = sessionId;
+    }
+    add(item) {
+        this.items.push(item);
+        this.vec.set(item.id, (0, text_embedding_1.textEmbedding)(item.content));
+    }
+    /** 질의와 가장 유사한 상위 k 항목 id(결정론적). */
+    topK(query, k = 5) {
+        const q = (0, text_embedding_1.textEmbedding)(query);
+        return this.items
+            .map((it) => ({ id: it.id, s: (0, text_embedding_1.cosineSimilarity)(q, this.vec.get(it.id)) }))
+            .sort((a, b) => b.s - a.s || (a.id < b.id ? -1 : 1))
+            .slice(0, k)
+            .map((x) => x.id);
+    }
+    size() { return this.items.length; }
+    snapshotItems() { return this.items.map((i) => ({ ...i })); }
+}
+exports.SessionContext = SessionContext;
+/**
+ * 도킹 — 동일 세션을 새 채널로 재귀속하되 이력·인덱스를 *그대로 이전*한다.
+ * (유실 없는 이전이 목표. 유실되면 §보존 측정에서 일치율 하락으로 드러난다.)
+ */
+function dockTo(session, toChannel) {
+    const t0 = (globalThis.performance?.now?.() ?? Date.now());
+    const fromChannel = session.channel;
+    // 이력·인덱스를 보존한 채 채널만 스위칭(동일 객체 재귀속).
+    session.channel = toChannel;
+    const latencyMs = (globalThis.performance?.now?.() ?? Date.now()) - t0;
+    return { session, fromChannel, toChannel, latencyMs };
+}
+/** 도킹 전후 top-k 일치율(교집합/ k). 1.0 = 완전 보존. */
+function preservationRatio(before, after) {
+    if (before.length === 0)
+        return 1;
+    const set = new Set(after);
+    const hit = before.filter((id) => set.has(id)).length;
+    return hit / before.length;
+}
+/** N개 질의에 대한 평균 top-k 보존율(도킹 전후). */
+function measurePreservation(session, queries, toChannel, k = 5) {
+    const before = queries.map((q) => session.topK(q, k));
+    const { latencyMs } = dockTo(session, toChannel);
+    const after = queries.map((q) => session.topK(q, k));
+    const ratios = before.map((b, i) => preservationRatio(b, after[i]));
+    const meanRatio = ratios.reduce((a, b) => a + b, 0) / (ratios.length || 1);
+    return { meanRatio, latencyMs, n: queries.length };
+}

package/dist/finance-mcts-candidate.d.ts

@@ -0,0 +1,37 @@
+import { ActionItem } from './mcts-prior';
+import { CandidateGenerator, FinanceRequest } from './finance-workflow';
+/** 금융 처리 행동 후보(이산 행동 공간). */
+export declare const FINANCE_ACTIONS: ActionItem[];
+/** 직접 승인 가능 상한(초과 시 상신). caveat 한도와 별개의 '처리 방식' 임계. */
+export declare const DIRECT_APPROVE_SOFT_LIMIT = 1000000;
+/**
+ * 룰 기반 가치 모델(외부 오라클로서의 trueValue) — 신경망 없음(claim 6).
+ * 요청 특성에 따라 각 처리 행동의 '바람직함'을 결정적으로 부여한다.
+ */
+export declare function ruleValueModel(req: FinanceRequest): Record<string, number>;
+/** 정적 프루닝 패턴(출원① 240) — 룰상 불가능한 행동을 실 Rust pruneActions로 제거. */
+export declare function staticPrunePatterns(req: FinanceRequest): string[];
+export interface MctsRecommendation {
+    chosenId: string;
+    chosenDescription: string;
+    survived: string[];
+    prunedOut: string[];
+    simsToConverge: number;
+    regret: number;
+    priorMode: 'embedding' | 'uniform';
+}
+export interface MctsCandidateOptions {
+    sims?: number;
+    cPuct?: number;
+    seed?: number;
+    priorMode?: 'embedding' | 'uniform';
+}
+/**
+ * 룰기반 MCTS(PUCT)로 처리 행동을 추천한다.
+ * 1) 실 Rust pruneActions 로 룰상 불가 행동 정적 제거
+ * 2) 임베딩 사전확률 P(s,a) (또는 균등 baseline)
+ * 3) 룰 가치(trueValue) 위에서 runPuctSearch(식(1) PUCT) sims회 탐색 → 최다방문 행동
+ */
+export declare function mctsRecommend(req: FinanceRequest, opts?: MctsCandidateOptions): MctsRecommendation;
+/** FinanceWorkflowEngine 에 주입할 룰기반 MCTS 후보 생성기(claim 6 결선). */
+export declare function mctsCandidateGenerator(opts?: MctsCandidateOptions): CandidateGenerator;

package/dist/finance-mcts-candidate.js

@@ -0,0 +1,106 @@
+"use strict";
+// ============================================================================
+// BM 출원③ 청구항6 결선 — 룰 기반 MCTS 후보 생성기 (금융 워크플로우)
+// ----------------------------------------------------------------------------
+// 출원③ 청구항6: "행동 후보 생성은, 학습된 신경역학망 없이 룰 기반 역학 모델로
+//   미래를 시뮬레이션하는 MCTS에 의해 수행된다" → FinanceWorkflowEngine 의
+//   CandidateGenerator 를 **실제 룰기반 MCTS 프리미티브**로 결선한다.
+//
+// 사용하는 실제 구성요소(전부 기구현·테스트됨):
+//   - `pruneActions` (Rust @n2world/core)        : 정적 행동 프루닝(출원① 240) — 룰상 불가 행동 제거
+//   - `embeddingWeightedPrior` (mcts-prior, P4)   : 사전확률 P(s,a)(출원② 650)
+//   - `runPuctSearch` (mcts-prior)                : 식(1) PUCT 탐색 a*=argmax[Q+c·P·√ΣN/(1+N)]
+//   - `lcg`                                        : 결정적 난수(재현성)
+//
+// 정직 고지(제1계명):
+//  - 가치(trueValue)는 **룰 기반 모델**(신경망 경사 업데이트 없음 — claim 6 핵심)이며,
+//    PUCT 보상의 외부 오라클 역할이다(자기 채점 아님).
+//  - 이는 금융 **행동 공간(승인/상신/보완/반려)** 위의 진짜 PUCT 탐색이다.
+//    그리드 MctsEngine(lib.rs, 내비게이션 모델)을 금융에 억지 매핑하지 않는다.
+//  - 후보 '선택'은 MCTS가 하되, 최종 승인/차단은 여전히 720 caveat·730 오라클이 강제한다.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECT_APPROVE_SOFT_LIMIT = exports.FINANCE_ACTIONS = void 0;
+exports.ruleValueModel = ruleValueModel;
+exports.staticPrunePatterns = staticPrunePatterns;
+exports.mctsRecommend = mctsRecommend;
+exports.mctsCandidateGenerator = mctsCandidateGenerator;
+const core_1 = require("@n2world/core");
+const mcts_prior_1 = require("./mcts-prior");
+/** 금융 처리 행동 후보(이산 행동 공간). */
+exports.FINANCE_ACTIONS = [
+    { id: 'approve_direct', content: '직접 승인 및 지급 큐 등록 — 소액·정상 경비' },
+    { id: 'escalate_manager', content: '관리자 상신 후 승인 — 고액 또는 송금' },
+    { id: 'request_info', content: '보완 요청 — 승인자 또는 정보 누락' },
+    { id: 'reject', content: '반려 — 규정 위반 또는 비정상 요청' },
+];
+/** 직접 승인 가능 상한(초과 시 상신). caveat 한도와 별개의 '처리 방식' 임계. */
+exports.DIRECT_APPROVE_SOFT_LIMIT = 1_000_000;
+const ALLOWED_CATEGORIES = ['travel', 'meal', 'office', 'vendor', 'payroll'];
+/**
+ * 룰 기반 가치 모델(외부 오라클로서의 trueValue) — 신경망 없음(claim 6).
+ * 요청 특성에 따라 각 처리 행동의 '바람직함'을 결정적으로 부여한다.
+ */
+function ruleValueModel(req) {
+    const nonCompliant = !(req.amount > 0) || !ALLOWED_CATEGORIES.includes(req.category);
+    const needsInfo = req.type === 'transfer' && !req.approver;
+    const heavy = req.type === 'transfer' || req.amount > exports.DIRECT_APPROVE_SOFT_LIMIT;
+    if (nonCompliant)
+        return { reject: 1.0, request_info: 0.4, escalate_manager: 0.2, approve_direct: 0.0 };
+    if (needsInfo)
+        return { request_info: 1.0, escalate_manager: 0.6, reject: 0.3, approve_direct: 0.1 };
+    if (heavy)
+        return { escalate_manager: 1.0, request_info: 0.5, approve_direct: 0.3, reject: 0.1 };
+    return { approve_direct: 1.0, escalate_manager: 0.4, request_info: 0.2, reject: 0.0 };
+}
+/** 정적 프루닝 패턴(출원① 240) — 룰상 불가능한 행동을 실 Rust pruneActions로 제거. */
+function staticPrunePatterns(req) {
+    const pats = [];
+    // 고액 또는 송금은 '직접 승인' 불가 → 후보에서 제거(상신/보완/반려만 남김).
+    if (req.amount > exports.DIRECT_APPROVE_SOFT_LIMIT || req.type === 'transfer')
+        pats.push('approve_direct');
+    return pats;
+}
+function contextString(req) {
+    return `${req.type} ${req.category} ${req.amount} ${req.payee} ${req.approver ? 'has-approver' : 'no-approver'}`;
+}
+/**
+ * 룰기반 MCTS(PUCT)로 처리 행동을 추천한다.
+ * 1) 실 Rust pruneActions 로 룰상 불가 행동 정적 제거
+ * 2) 임베딩 사전확률 P(s,a) (또는 균등 baseline)
+ * 3) 룰 가치(trueValue) 위에서 runPuctSearch(식(1) PUCT) sims회 탐색 → 최다방문 행동
+ */
+function mctsRecommend(req, opts = {}) {
+    const sims = opts.sims ?? 240;
+    const cPuct = opts.cPuct ?? 1.4;
+    const seed = opts.seed ?? 12345;
+    // 1) 정적 프루닝(실 Rust)
+    const patterns = staticPrunePatterns(req);
+    const keptIds = (0, core_1.pruneActions)(exports.FINANCE_ACTIONS.map((a) => a.id), patterns);
+    const survived = exports.FINANCE_ACTIONS.filter((a) => keptIds.includes(a.id));
+    const prunedOut = exports.FINANCE_ACTIONS.filter((a) => !keptIds.includes(a.id)).map((a) => a.id);
+    // 2) 사전확률 P(s,a)
+    const priors = opts.priorMode === 'uniform'
+        ? (0, mcts_prior_1.uniformPrior)(survived)
+        : (0, mcts_prior_1.embeddingWeightedPrior)(survived, contextString(req));
+    // 3) 룰 가치 위에서 진짜 PUCT 탐색
+    const tvAll = ruleValueModel(req);
+    const trueValue = {};
+    for (const a of survived)
+        trueValue[a.id] = tvAll[a.id] ?? 0;
+    const res = (0, mcts_prior_1.runPuctSearch)(survived, priors, trueValue, sims, cPuct, (0, mcts_prior_1.lcg)(seed));
+    const chosen = survived.find((a) => a.id === res.finalBestId) ?? survived[0];
+    return {
+        chosenId: chosen.id,
+        chosenDescription: `${chosen.content} :: ${req.payee} ${req.amount.toLocaleString('ko-KR')}원(${req.category})`,
+        survived: survived.map((a) => a.id),
+        prunedOut,
+        simsToConverge: res.simsToConverge,
+        regret: res.regret,
+        priorMode: opts.priorMode === 'uniform' ? 'uniform' : 'embedding',
+    };
+}
+/** FinanceWorkflowEngine 에 주입할 룰기반 MCTS 후보 생성기(claim 6 결선). */
+function mctsCandidateGenerator(opts = {}) {
+    return (req) => mctsRecommend(req, opts).chosenDescription;
+}

package/dist/finance-regulation-kr.d.ts

@@ -0,0 +1,33 @@
+import { FinanceRequest } from './finance-workflow';
+export type RuleSeverity = 'block' | 'flag';
+export interface RegulationRule {
+    id: string;
+    /** 법적/정책 근거(검토 표식 — 단정 아님). */
+    basis: string;
+    description: string;
+    severity: RuleSeverity;
+}
+export interface RegulationEvaluation {
+    /** 거래를 차단해야 하는 위반(severity 'block'). */
+    blocks: string[];
+    /** 차단하지 않되 보고/추가검토 대상(severity 'flag' — 예: CTR/STR). */
+    flags: string[];
+    /** 발동한 규칙 id(감사용). */
+    firedRuleIds: string[];
+}
+export interface RegulationRuleSet {
+    jurisdiction: string;
+    version: string;
+    /** 허용 계정과목(조직 정책). */
+    allowedCategories: string[];
+    /** 고액거래 보고 검토 임계(특금법 CTR은 본래 '현금'거래 기준 — 적용대상 검증필요). */
+    highValueReportThreshold: number;
+    /** 단일 송금 상한(내부통제·전자금융 한도 — 조직정책/검증필요). */
+    singleTransferMax: number;
+    rules: RegulationRule[];
+    evaluate(req: FinanceRequest): RegulationEvaluation;
+}
+export declare const KR_FINANCE_RULES: RegulationRule[];
+export declare function createKrFinanceRuleSet(overrides?: Partial<Pick<RegulationRuleSet, 'allowedCategories' | 'highValueReportThreshold' | 'singleTransferMax'>>): RegulationRuleSet;
+/** 기본 KR 규정셋(초안). */
+export declare const KR_FINANCE_RULESET: RegulationRuleSet;

package/dist/finance-regulation-kr.js

@@ -0,0 +1,104 @@
+"use strict";
+// ============================================================================
+// BM 출원③ — 관할(대한민국) 금융 규정셋 (구성 가능한 스캐폴드)
+// ----------------------------------------------------------------------------
+// FinanceOracle(730)가 소비하는 **외부화된 규정 규칙**. 데모 하드코드를 대체해
+// 규정 근거·임계를 한 곳에서 관리·검토하게 한다(법무 검토 단위).
+//
+// ⚠ 법적 면책(중요): 본 모듈은 **법률 자문이 아니며**, 모든 임계값·적용대상·근거는
+//   **변호사/준법감시(컴플라이언스) 정식 검토 전 초안**이다. `basis`의 법령 인용과
+//   `(검증필요)`/`(조직정책)` 표기는 검토 항목 표식일 뿐 법적 사실의 단정이 아니다.
+//   실제 적용 전 관할 규정·최신 개정·기관별 적용대상을 반드시 확인하라(제1계명).
+//
+// 구분: severity 'block'=거래 차단, 'flag'=차단 않되 보고/추가검토 대상(예: CTR/STR).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KR_FINANCE_RULESET = exports.KR_FINANCE_RULES = void 0;
+exports.createKrFinanceRuleSet = createKrFinanceRuleSet;
+// ─────────────────────────────────────────────────────────────────────────
+// 대한민국(KR) 기본 규정셋 — 초안(검토 전). 임계는 조직/관할에 맞게 재확인.
+// ─────────────────────────────────────────────────────────────────────────
+exports.KR_FINANCE_RULES = [
+    {
+        id: 'KR-CAT-001',
+        basis: '내부회계관리·계정과목 정책(조직정책)',
+        description: '사전 승인된 계정과목만 처리한다.',
+        severity: 'block',
+    },
+    {
+        id: 'KR-SOD-001',
+        basis: '내부통제·직무분리(SoD) 원칙 / 내부회계관리제도(검증필요)',
+        description: '품의자와 승인자는 동일인일 수 없다(직무분리).',
+        severity: 'block',
+    },
+    {
+        id: 'KR-APPROVAL-001',
+        basis: '전자금융거래법상 이체 통제·내부 승인절차(검증필요)',
+        description: '송금(이체)은 승인자 지정이 필수다.',
+        severity: 'block',
+    },
+    {
+        id: 'KR-XFER-LIMIT-001',
+        basis: '전자금융 이체한도·내부통제 한도(조직정책/검증필요)',
+        description: '단일 송금이 한도를 초과하면 차단(상위 승인 경로 필요).',
+        severity: 'block',
+    },
+    {
+        id: 'KR-CTR-001',
+        basis: '특정금융정보법(특금법) 고액현금거래보고(CTR) — 적용대상/현금기준 검증필요',
+        description: '고액 임계 이상 거래는 보고/추가검토 대상으로 플래그(차단 아님).',
+        severity: 'flag',
+    },
+    {
+        id: 'KR-STR-001',
+        basis: '특금법 의심거래보고(STR) — 의심 정황 판단기준 검증필요',
+        description: '이중지급 의심 등 비정상 정황은 보고/추가검토 대상으로 플래그.',
+        severity: 'flag',
+    },
+];
+function createKrFinanceRuleSet(overrides = {}) {
+    const allowedCategories = overrides.allowedCategories ?? ['travel', 'meal', 'office', 'vendor', 'payroll'];
+    const highValueReportThreshold = overrides.highValueReportThreshold ?? 10_000_000; // (검증필요)
+    const singleTransferMax = overrides.singleTransferMax ?? 50_000_000; // (조직정책/검증필요)
+    return {
+        jurisdiction: 'KR',
+        version: 'draft-v1.0(검토전)',
+        allowedCategories,
+        highValueReportThreshold,
+        singleTransferMax,
+        rules: exports.KR_FINANCE_RULES,
+        evaluate(req) {
+            const blocks = [];
+            const flags = [];
+            const firedRuleIds = [];
+            // KR-CAT-001 (block)
+            if (!allowedCategories.includes(req.category)) {
+                blocks.push(`[KR-CAT-001] 허용외 계정과목: ${req.category}`);
+                firedRuleIds.push('KR-CAT-001');
+            }
+            // KR-SOD-001 (block)
+            if (req.approver && req.approver === req.requester) {
+                blocks.push('[KR-SOD-001] 직무분리 위반(품의자=승인자)');
+                firedRuleIds.push('KR-SOD-001');
+            }
+            // KR-APPROVAL-001 (block)
+            if (req.type === 'transfer' && !req.approver) {
+                blocks.push('[KR-APPROVAL-001] 송금 승인자 미지정');
+                firedRuleIds.push('KR-APPROVAL-001');
+            }
+            // KR-XFER-LIMIT-001 (block)
+            if (req.type === 'transfer' && req.amount > singleTransferMax) {
+                blocks.push(`[KR-XFER-LIMIT-001] 단일 송금 한도 초과(${req.amount} > ${singleTransferMax})`);
+                firedRuleIds.push('KR-XFER-LIMIT-001');
+            }
+            // KR-CTR-001 (flag — 차단 아님)
+            if (req.amount >= highValueReportThreshold) {
+                flags.push(`[KR-CTR-001] 고액거래 보고/추가검토 대상(${req.amount} ≥ ${highValueReportThreshold})`);
+                firedRuleIds.push('KR-CTR-001');
+            }
+            return { blocks, flags, firedRuleIds };
+        },
+    };
+}
+/** 기본 KR 규정셋(초안). */
+exports.KR_FINANCE_RULESET = createKrFinanceRuleSet();

package/dist/finance-workflow.d.ts

@@ -0,0 +1,135 @@
+import { A2ATrustGate, A2AContext } from './agent-os-rd';
+import { GovernanceController } from './governance';
+import type { RegulationRuleSet } from './finance-regulation-kr';
+export type FinanceRequestType = 'expense' | 'transfer';
+/** 금융 품의 요청(채널 세션에서 정규화되어 들어온다고 가정). */
+export interface FinanceRequest {
+    id: string;
+    channel: string;
+    requester: string;
+    type: FinanceRequestType;
+    payee: string;
+    amount: number;
+    date: string;
+    category: string;
+    approver?: string;
+    memo?: string;
+}
+/** 720 — 토큰에 부가된 금융 규제 caveat(문자열 표현). */
+export declare const FinanceCaveat: {
+    readonly amountMax: (limit: number) => string;
+    readonly approvalRequired: () => string;
+    readonly segregationOfDuties: () => string;
+    readonly categoryAllow: (cats: string[]) => string;
+};
+export interface WorkflowControl {
+    /** 어떤 통제에서 결정됐는가(측정·감사용). */
+    control: 'trust' | 'caveat' | 'oracle' | 'execute';
+    passed: boolean;
+    reason: string;
+}
+export interface WorkflowDecision {
+    requestId: string;
+    approved: boolean;
+    /** 최초로 실패한 통제(통과 시 'execute'). */
+    decidedBy: WorkflowControl['control'];
+    controls: WorkflowControl[];
+    /** 가치 v∈[0,1](사업 우선순위) — 신뢰 t와 독립. */
+    value: number;
+    /** 신뢰 t∈[0,1]. */
+    trust: number;
+    violations: string[];
+    /** 감사 추적 id. */
+    auditId: string;
+}
+export declare class FinanceCaveatVerifier {
+    private secret;
+    constructor(secret: string);
+    /**
+     * ① 실제 MacaroonVerifier 로 서명체인·기본 caveat(target/expires/path) 검증
+     * ② 금융 caveat(fin.*)을 요청에 대해 강제
+     * 반환: { ok, violations }. 위반 사유는 감사 로그로 남는다.
+     */
+    check(token: string, req: FinanceRequest, ctx: A2AContext): {
+        ok: boolean;
+        violations: string[];
+    };
+}
+export interface OracleResult {
+    passed: boolean;
+    violations: string[];
+    cheatDetected: boolean;
+    /** 차단하지 않되 보고/추가검토 대상(예: CTR/STR 플래그). */
+    flags?: string[];
+}
+export declare class FinanceOracle {
+    /** 정책상 허용 계정과목(독립 정의 — 에이전트가 수정 못함). 규정셋 미지정 시 사용. */
+    private readonly allowedCategories;
+    /** 이중지급 판정 키. */
+    private readonly dedupeKey;
+    /** 관할 규정셋(옵션). 지정 시 계정과목·SoD·승인·한도·고액보고를 규정셋이 결정. */
+    private readonly ruleset?;
+    /** 이중지급 탐지용 원장: (payee|amount|date) → 최초 요청 id. */
+    private paidLedger;
+    constructor(
+    /** 정책상 허용 계정과목(독립 정의 — 에이전트가 수정 못함). 규정셋 미지정 시 사용. */
+    allowedCategories?: string[], 
+    /** 이중지급 판정 키. */
+    dedupeKey?: (r: FinanceRequest) => string, 
+    /** 관할 규정셋(옵션). 지정 시 계정과목·SoD·승인·한도·고액보고를 규정셋이 결정. */
+    ruleset?: RegulationRuleSet | undefined);
+    validate(req: FinanceRequest, generatedAction: string): OracleResult;
+}
+export interface AuditEntry {
+    auditId: string;
+    requestId: string;
+    ts: number;
+    decidedBy: WorkflowControl['control'];
+    approved: boolean;
+    trust: number;
+    value: number;
+    violations: string[];
+}
+export declare class AuditLog {
+    private entries;
+    private seq;
+    record(e: Omit<AuditEntry, 'auditId' | 'ts'>): string;
+    all(): AuditEntry[];
+}
+/** 행동 후보 생성기(주입형). 프로덕션 경로는 출원① 룰기반 MCTS. */
+export type CandidateGenerator = (req: FinanceRequest) => string;
+export interface FinanceEngineOptions {
+    secret: string;
+    trustGate: A2ATrustGate;
+    oracle?: FinanceOracle;
+    audit?: AuditLog;
+    candidateGenerator?: CandidateGenerator;
+    /** 가치 v 정규화 기준 금액(이 금액에서 v≈1). 신뢰 t와 독립. */
+    valueRefAmount?: number;
+    /** 운영자 킬스위치. true면 모든 자동화 중단. */
+    killSwitch?: () => boolean;
+    /** 740 거버넌스 결선(옵션) — 지정 시 킬스위치는 governance.isKilled()도 함께 보고,
+     *  모든 결정을 governance.record()로 흘려 영속 sink(디스크 등)에 내구 기록한다. */
+    governance?: GovernanceController;
+}
+export declare class FinanceWorkflowEngine {
+    private verifier;
+    private trustGate;
+    private oracle;
+    private audit;
+    private gen;
+    private valueRef;
+    private killSwitch;
+    private governance?;
+    constructor(opts: FinanceEngineOptions);
+    auditLog(): AuditLog;
+    /** 가치 v∈[0,1]: 사업 우선순위(금액 비례, 상한 1). 신뢰 t와 독립 산출. */
+    private computeValue;
+    /**
+     * 금융 품의 1건을 처리한다. 통제 순서: 킬스위치 → 신뢰(t) → caveat(720) → 오라클(730) → 실행.
+     * 각 단계 결과를 controls 에 누적하고 감사 로그에 기록한다.
+     */
+    process(req: FinanceRequest, token: string, ctx: A2AContext): WorkflowDecision;
+}
+/** 헬퍼: 역할/세션에 금융 caveat 를 부가한 위임 토큰 발급(720). */
+export declare function issueFinanceToken(secret: string, identifier: string, target: string, caveats: string[]): string;